DarDocs
Besides the biggy of source control another advantage of having an XML-based offline system of record of our Documentum artefacts is that we can use standard XML tools on those artefacts.
For example you could generate HTML docs from them; DarDocs if you will.
Take a transform like this:-
<!–XML Transform to generate HTML from Documentum Type Artefacts–>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:lxslt="http://xml.apache.org/xslt"
xmlns:xmi="http://www.omg.org/XMI" xmlns:Artifact="http://documentum.emc.com/infrastructure/12012007/artifact" >
<xsl:template match="/">
<html>
<body>
<table border="1">
<xsl:for-each select="Artifact:Artifact/dataModel/type">
<tr>
<td>Document Type</td>
<td><xsl:value-of select="@name"/></td>
</tr>
<tr>
<td>Super Type</td>
<td><xsl:value-of select="substring-before(substring-after(super_name/@href,’name=’), ‘#’)"/></td>
</tr>
<tr bgcolor="#9acd32">
<th>Attribute Name</th>
<th>Attribute Type</th>
<th>Attribute length</th>
<th>Attribute Label</th>
<th>Help Text</th>
<th>Comment</th>
</tr>
<xsl:for-each select="primaryElement/attributes">
<tr>
<td><xsl:value-of select="@attr_name"/></td>
<td><xsl:value-of select="attr_type/@values"/></td>
<td><xsl:value-of select="@attr_length"/></td>
<td><xsl:value-of select="attrAnnotations/locales/@label_text"/></td>
<td><xsl:value-of select="attrAnnotations/locales/@help_text"/></td>
<td><xsl:value-of select="attrAnnotations/locales/@comment_text"/></td>
</tr>
</xsl:for-each>
</xsl:for-each>
</table>
</body>
</html>
</xsl:template>
</xsl:stylesheet>
And a simple ant task like this:-
<?xml version="1.0" encoding="UTF-8"?>
<project default="generateDocs">
<target description="Generate DarDocs" name="generateDocs">
<xslt basedir="Artifacts" destdir="Documents" style="style/DocTypes.xsl">
<mapper type="glob" from="*.type" to="*.html"/>
</xslt>
</target>
</project>
And run it over a project with a few types in and you should get an html file for each type that looks something like this:-
| Document Type | soptype | ||||
| Super Type | dm_document | ||||
| Attribute Name | Attribute Type | Attribute length | Attribute Label | Help Text | Comment |
|---|---|---|---|---|---|
| attr1 | STRING | 10 | attr1_label | Some user help on attr1 | Developer comment for attr1 |
| attr2 | INTEGER | 10 | attr2 label | Some user help for attr2 | Developer comment for attr2 |
It would be simple enough for a release engineer to add this to your releng build so that each build also produces a set of DarDocs for your Dars.
Hat tip to Eddie Doey from UK Consulting for providing this great example.
Happy Composing!
May 29, 2009 at 12:55 pm
Great idea Paul. One of those decision on how to document the object model but with this we can document/build at the same time.
Thanks!
July 30, 2009 at 5:16 pm
With some creativity, we could also generate code/scripts off this XML and execute them as well through ANT.
Six years ago, I was getting started with Documentum and was trying to figure out an efficient development approach for setting up Documentum environments. I created an Eclipse project with an ANT build script to do the following:
1. Define commonly needed configuration using XML. This included type definition, groups, users, group memberships, ACL’s, data objects, folder hierarchies. Some configuration, such as type definition, would be for one-time use, to bootstrap docapp creation.
2. Generate scripts (DQL/API) to “install” this configuration into a repository. The script generation was achieved using XSL.
3. Generate HTML documentation for the configuration, again using XSL.
4. Execute scripts against specific environments – DEV, UA, etc. The execution was performed using ANT targets. The environment connection information was stored in properties files.
5. The XML and XSL files were source-controlled. The scripts were put under version control when they were used for deployment to production.
Throw in some PERL (or other scripting/extract-transform) wizardry to convert all sorts of data from various sources into the XML configuration mentioned above and you have quite a powerful engine in your hands.
This approach works quite well and is perfectly compatible with Composer due to its reliance on XML. In addition to generating scripts, boilerplate Java code could also be generated from the same XML. I won’t be surprised at all if Documentum products are already using similar approaches internally.
Exciting times indeed!
August 19, 2009 at 10:03 am
Simply creating an XML-based system of record that can be source controlled alongside other regular engineering resources is a definite step fowards IMHO. I find Composer exciting because of the possibilities that it this presents, some you have highlighted.
One of my goals for the near future is to morph Composer back into what I had originally intended – a tooling platform, rather than what it ended up as – a tooling application; so that we can extend these possibilities to the partners and customers.
Many thanks for the comment doquent. I know this will “enlighten” others.