Propagate AEM Assets metadata to DITA-OT plugin generated output

In this article we will explain how to implement changes to DITA-OT plugin to read the metadata.xml (available in temporary files) and utilize the properties, passed by AEM Guides publishing workflow, in DITA-OT plugins and set it in the generated output.

On a high level, below are the steps that you will learn in this article:

Background

With AEM Guides, you can use DITA-OT plugins to publish to output formats of your choice using the configured plugins, and
you can also pass metadata of the assets managed in AEM DAM to the DITA-OT process to use it in the generated output - see the documentation on how to setup ditamap/topics to pass metadata through output preset

Assumptions

You have a AEM setup with AEM Guides version 4.4.0/2024.6 or above
You have prior knowledge of how DITA-OT works and its directory structure

Steps explained

Setting metadata on the asset

With AEM Assets Metadata Schema you can create custom property fields for the Assets in AEM, and users can assign metadata to the assets. Taking an example of a topic asset where a metadata named customprop can be set for an example - refer screenshot below:

Configuring the metadata on ditamap output preset to pass to DITA-OT

Configure output preset of your choice on the map to export metadata and pass to DITA-OT
Let us say we are generating HTML5 output using a DITA-OT plugin say adobe.html.
See screenshot below to understand how to configure the output preset for a map to pass metadata to the DITA-OT plugin.

Refer screenshot below to understand the steps given above:

Implementing the DITA-OT plugin

Accessing the metadata.xml in temporary directory

In the downloaded temporary files package, you will notice a metadata.xml file where you can see the structure of the properties and values (see screenshot below)

Understand metadata.xml

        <Path id="topics\about-this-document.dita">
            <sourceProps>
                ...
            </sourceProps>
            <metadata>
                <meta isArray="false" key="dc:title">About This Document</meta>
                <meta isArray="false" key="customprop">customval</meta>
            </metadata>
        </Path>

Accessing the metadata for each asset in DITA-OT plugin

For the DITA-OT plugin to read the metadata.xml and properties available in it we need to do following:

<?xml version="1.0" encoding="UTF-8"?>
<plugin id="com.adobe.html">
    <require plugin="org.dita.html5"/>
    <feature extension="dita.conductor.transtype.check" value="adobe.html"/>
    <feature extension="ant.import" file="integrator.xml"/>
    <feature extension="dita.conductor.html5.param" file="params.xml"/>
    <feature extension="package.version" value="2024.1"/>
</plugin>

    <property name="adobe.html.xsl.dir" value="${dita.plugin.com.adobe.html.dir}${file.separator}xsl${file.separator}"/>
    <property name="args.xsl" location="${adobe.html.xsl.dir}adobe-html5.xsl" />
    <dirname property="input.dirname" file="${args.input}"/>
    <makeurl file="${input.dirname}/metadata.xml" property="metadata.url"/>

    <?xml version="1.0" encoding="UTF-8"?>
    <params xmlns:if="ant:if">
        <param name="metadata.url" expression="${metadata.url}" if:set="metadata.url"/>
    </params>

<xsl:import href="plugin:org.dita.html5:xsl/dita2html5.xsl"/>
    <xsl:param name="metadata.url"/>
    <xsl:template name="copyright">
        <xsl:if test="doc-available( $metadata.url )">
            <xsl:variable name="docName" select="tokenize( base-uri(), '/' )[ last() ]"/>
            <xsl:variable name="doc" select="doc( $metadata.url )"/>
            <xsl:for-each select="$doc//Path[ ends-with( @id, concat( '\', $docName ) ) ]/metadata/meta">
                <meta name="{ @key }" content="{ . }"/>
            </xsl:for-each>
        </xsl:if>
    </xsl:template>

Refer screenshot below highlighting the steps above

Testing the plugin Implementation

You can test the plugin by running following command to test it with the temporary files downloaded from AEM (which has map content and its metadata.xml)

./dita --input=docsrc/samples/HTML5/aem_forms_documentation.ditamap --format=adobe.html

Assuming you have copied the downloaded temporary files under the directory “DITA-OT/docsrc/samples/HTML5”.
You can also download the sample given in resources section below.

When the above command is executed you can check the output in the directory “DITA-OT/bin/out”, where you can check the html files generated for the topic “about-this-document.dita” which will have the custom metadata in the head element

<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <meta charset="UTF-8">
    <meta name="copyright" content="(C) Copyright 2024">
    <meta name="DC.format" content="HTML5">
    <meta name="DC.identifier" content="GUID-f193ea85-989d-4d80-99e2-2f5dea3d5310">
    <meta name="DC.language" content="en-US">
    <meta name="dc:title" content="About This Document">
    <meta name="customprop" content="customval">
    <title>About This Document</title>
</head>

Deployment

Once you have developed the DITA-OT plugin, you can integrate this in the DITA-OT using dita --install command under the DITA-OT directory, and deploy it to the AEM server refer this article for more details

Resources