links for 2009-02-12

Posted by Mike Thu, 12 Feb 2009 16:24:05 GMT

no comments | no trackbacks

links for 2009-02-10

Posted by Mike Wed, 11 Feb 2009 00:31:18 GMT

no comments | no trackbacks

links for 2009-02-09

Posted by Mike Tue, 10 Feb 2009 00:30:50 GMT

no comments | no trackbacks

links for 2009-02-04

Posted by Mike Thu, 05 Feb 2009 00:31:05 GMT

no comments | no trackbacks

links for 2009-01-29

Posted by Mike Fri, 30 Jan 2009 00:31:06 GMT

no comments | no trackbacks

links for 2009-01-27

Posted by Mike Wed, 28 Jan 2009 00:31:02 GMT

no comments | no trackbacks

links for 2009-01-23

Posted by Mike Sat, 24 Jan 2009 00:30:46 GMT

no comments | no trackbacks

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:

  1. Add a <Comments> element or @description XML comment to your waveset object. See below for list of supported elements.

  2. 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.)

  3. 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">

  4. 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.

Posted in  | Tags , ,  | no comments | no trackbacks

Older posts: 1 ... 3 4 5 6 7 ... 44