Sample use case: Add a new customization plugin

To create a new transformation scenario that uses the DITA Open Toolkit, you create a plugin that contains a new transtype and the customization for the DITA-OT transformation.

For example, you may want to add a new plugin to the DITA Open Toolkit to integrate a new transformation scenario or to add open source plugins such as the DITA for Publishers plugin or the DITA QA plugin.

Note: This procedure assumes that the plugin was created using the procedure in the DITA Open Toolkit documentation. See the DITA Open Toolkit User Guide for more information.
In general, there are three main steps involved in adding a new plugin:
  • Install the plugin
  • Link the plugin to the IXIA CCMS Output Generator by creating a target
  • Make it visible to your users

The following procedure gives an example of how to add the QA plugin for DITA-OT to CCMS Output Generator. This plugin checks your DITA content and provides a Quality Assurance (QA) report that lists errors in the DITA usage in your files (incorrect DITA tagging, language standards, etc.).

Note: This procedure assumes that you have downloaded the open source plugin called org.dita-community.qa from the web at github.com/dita-community/org.dita-community.qa. MadCap Software does not maintain this plugin.

To add a new plugin:

  1. Extract the plugin to the %OutputGenDir%/data/%OT_Dir%/plugins directory.
    For example:
    C:\ixiasoft\OutputGenerators\Prod_[version]\data\dita-ot-2.5.4\plugins\

    Where [version] is replaced by the release version number.

  2. Run the DITA-OT integrator.
    This step depends on the DITA-OT family:
    DITA-OT 1.x family:
    • If lower than 1.6.2, contact IXIA CCMS Customer Support.
    • On Windows: In the %OutputGenDir%/data/ directory, double-click the _DITA-OT-1.x.x-integrator.bat file.
    • On Linux:
      1. In the %OutputGenDir%/data/%OT_Dir%/ directory, run the following command as root:
        startcmd.sh
      2. At the command prompt, enter:
        ant -f integrator.xml

    The integration build runs and you should soon see BUILD SUCCESSFUL.

    DITA-OT 2.x and 3.x family:
    • On Windows: In the %OutputGenDir%/data/ directory, double-click the _DITA-OT-x.x.x-install.bat.
    • On Linux: In the %OutputGenDir%/data/ directory, double-click the _DITA-OT-x.x.x-install.sh.

    The integration build runs and you should soon see BUILD SUCCESSFUL.

  3. Create a target in your client conductor file (for example, %OutputGenDir%/data/conductor-acme.xml), as described in Create a transformation target.
    Note: You can use the client.FooBarwrapper target in the %OutputGenDir%/data/conductor-client.xml.orig file as a template to create your target.
    The target should be similar to the following:
    <target name="acme.dita2qareport" depends="default_dependencies, flatten, resolve_container_keyref, extract_HiRes_images">
    	<echostart>acme.dita2qareport</echostart>
    
    	<ot_build_add_ditaval_ifpresent/>
    	<ot_build_clean_ot_temp/>
    	<ot_build_keep_topicfo/>
    
    	<ot_build_set_parameter name="transtype" value="qa"/>
    
    	<dita_startcmd_ot_build/>
    
    	<clean_ot_output/>
    
    	<!-- Set the property job.keep.temp to preserve the completed temp folder of the task -->
    	<!--<property name="job.keep.temp" value="yes"/>-->
    
    	<echoend>acme.dita2qareport</echoend>
    </target>
  4. Create a preprocessor for the plugin in the %OutputGenDir%/conf/client/preprocessors.xml file, as described in Add a new preprocessor.
    The preprocessor should be similar to the following:
    <preprocessor name="qareport" class="com.ixiasoft.outputgenerator.preprocessor.AntProcessor" >
        <parameters>
            <system>
                <parameter name="outputfile" value=".html"/>
                <parameter name="buildfile" value="/conductor-client.xml"/>
                <parameter name="target" value="acme.dita2qareport"/>
                <parameter name="clean" value="job_postprocess"/>
                <parameter name="keep.log.files" value="true"/>
            </system>
        </parameters>
    </preprocessor>
  5. Create an output type for the plugin in the %OutputGenDir%/conf/client/outputtypes.xml file, as described in Add a new output type.
    The output type should be similar to the following:
    <outputtype name="QA_Report" timeout="120000" system="false">
        <preprocessing>
            <preprocessor name="qareport" />
        </preprocessing>
        <renderer/>
    </outputtype>
  6. Restart the Ixiasoft Output Generator service.
    You can now use the new transformation scenario.