Documenting Sun IDM XML Objects
Posted by Mike Fri, 23 Jan 2009 18:23:00 GMT
Note 1: this post details an approach for documenting the configuration objects of Sun's Identity Manager product. It's propbably not interesting unless you're an IDM developer.
Note 2: the following article applies to IDM 7.1. Not sure about earlier or later versions.
IDM's XML configuration objects have limited support for in-situ programmer comments. Most high-level elements allow <Comments> elements, while others support a description attribute. Herewith an approach that leverages the existing documentation aspects of the Waveset.dtd, generic XML comment notation, and the waveset XML data iteself to generate IDM implementation documentation.
A schematic that shows how the approach takes waveset XML objects and converts them to standard document formats:
For the impatient, the XSL that transforms Waveset XML to Docbook XML is waveset2docbook.xsl.
Documenting a Single XML Object
A recipe for generating documentation from an IDM configuration XML file:
Add a <Comments> element or @description XML comment to your waveset object. See below for list of supported elements.
-
Using your favourite XSL processor, transform the waveset XML object to Docbook format using waveset2docbook.xsl.
I use xsltproc, e.g.:mpierson:$ xsltproc --stringparam fileName "custom/WEB-INF/config/MyResource.xml" \ waveset2docbook.xsl custom/WEB-INF/config/MyResource.xml > docs/MyResource.xml
(The fileName stringparam allows the file's path in the CBE to be included in the documentation.)
-
Add an XML declaration to the generated Docbook file:
<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-
Open the generated Docbook XML in OpenOffice using file type Docbook. This should work in versions 2.x and 3.x of OpenOffice.
- or -
Use the Docbook XSL stylesheets to convert your generated Docbook file to HTML or PDF (or many other formats).
Using the above recipe, I've documented a sample LDAP resource adapter definition:
MyResource.xml -> MyResource.dbk -> MyResource.doc
Documenting the Entire IDM Implementation
A more practical application of this approach to IDM docs, is to produce a single 'as-built' document for all configured XML objects. This is best achived via a script, which repeats the procedure for a single XML waveset object, and appends each result to a single Docbook document.
An example script that does just this (including the required Docbook XML declaration) is here. You'll see in the script that I like the generated docs to be included as an appendix in the project documentation.
Supported Waveset Elements
The current version of waveset2docbook.xsl supports a subset of the waveset.dtd, but includes most of the high-level elements.
| Element | Description Element | Other Aspects Documented |
|---|---|---|
| Configuration:User Extended Attributes | none | extended attributes are enumerated |
| Configuration:UserUIConfig | none | SummaryAttrNames, QueryableAttrNames, FindSearchAttrs, RepoIndexAttrs |
| Configuration:Reconciliation Policy | none | reconciliation policy attributes (fetch timeout etc.), plus per-resource type configuration (correlation rule, confirmation rule, proxy user, etc.) |
| LoginApp | @description | LoginModGroups are enumerated |
| LoginModGroup | none | resource type, module type, control type, correlation rule, authentication parameters |
| Organizations | @description | path from Top, policies |
| Policy:Account Policy | Description element | account ID policy, password policy |
| Policy:String Quality Policy | Description element | string quality policy attributes are enumerated |
| Resource | @description | flat file format attributes, @prodRef for reference to IDM resource documentation, active sync attributes (proxy user, correlation rule, confirmation rule), |
| Rule | Comments element | rule type (correlation, confirmation, other) |
| Configuration:Rule Library | none | documented rules are enumerated, including contents of Comment element in each rule |
| EmailTemplate | Comments element | status of 'html enabled' flag |
| TaskDefinition | Comments element | referenced sub-tasks, referenced forms |
| Configuration:WFProcess (sub-task) | Comments element | referenced sub-tasks, referenced forms |
| Configuration:Custom Catalog | none | name and value of each message is listed |
| TaskSchedule | Description element | task to run, repitition count and unit |
| User | @description | user form, admin groups, organizations |
| User Form | Comments element | referenced forms |
OpenOffice And Docbook
It's worth noting that OpenOffice supports Docbook 'out-of-the-box', but not all elements are supported. I've adapted the docbook XSL filter from OpenOffice 3.0 to do a better job of rendering the <literallayout> elements generated by waveset2docbook.xsl. Download it here, your results may vary. The OpenOffice site has instructions for customizing the XML filters, but I just used the Tools -> XML Filter Settings in OO 3.0.
