Create a transformation target

This procedure describes how to create a transformation target and add it to a conductor file.

Targets are defined in your client conductor file (for example, %OutputGenDir%/data/conductor-acme.xml) in a <target> element.

Note: Conductor files are written in Ant, so this procedure assumes that you have some knowledge in programming Ant scripts. For further background information on building Ant projects, see the Apache Ant site: http://ant.apache.org. For information on the DITA Open Toolkit, see http://www.dita-ot.org/.

To execute a transformation scenario, a target usually goes through the following process:

Prepare the execution environment
Prepare the content for the transformation
Create the build script
Run the build script
Clean up the files

There are two essential directories when creating a transformation scenario:

Input directory: When the IXIASOFT Output Generator retrieves the files from the Content Store, it stores them in this directory, defined with the outgen.job.source.dir Ant property. If you need to modify the files before transforming them, you need to modify them in this directory.
Note: If you are working with a branched map, you must call the flatten target before modifying the source files. The flatten target will copy all the working and published files to the input directory so that you can modify them as required.
Output directory: Any file that is stored in this directory at the end of the transformation job will be returned to the end user in a zip file. This directory is defined with the outgen.job.output.dir property. Make sure to clean up your directory as required and to keep all the files that must be returned to the user.

The following procedure describes how to create the acme.dita2xHtmlwrapper target, which transforms DITA files into HTML. The final target will look as follows:

<target name="acme.dita2xHtmlwrapper" depends="default_dependencies, flatten, extract_LowRes_images">
   <property name="outgen.job.build.filename" 
             location="${outgen.job.dir}/build.xml"/>
   <property name="outgen.job.build.template.filename" 
             location="${outgen.resources.dir}/job-build-template.xml"/>
   <property name="outgen.job.build.otlog.filename" 
             location="${outgen.job.ot.log.dir}/${outgen.job.source.name.noext}.ot.log"/>

   <antcall target="ot_build_create"/>
   <antcall target="ot_build_add_ditaval_ifpresent"/>
   <antcall target="ot_build_clean_ot_temp"/>

   <update-ot-build-file buildfile="${outgen.job.build.filename}">
      <param name="transtype" value="xhtml"/>
   </update-ot-build-file>

   <antcall target="dita_startcmd_ot_build"/>

   <antcall target="clean_ot_output"/>
</target>

Since conductor files are like programming files, each target is different and does not follow a specific structure, like output type or processor files do. This section describes how to create a target that transforms DITA files to HTML using the DITA Open Toolkit, but you can create many different types of targets.

To create a transformation target:

Open your client conductor file (for example, %OutputGenDir%/data/conductor-acme.xml).
You can also create a new client conductor file. Conductor files must be stored directly in the %OutputGenDir%/data directory.
Create a target element and specify the name of the target:
```
<target name="acme.dita2xHtmlwrapper"
```
IXIASOFT recommends that you add your company name before the target name. In the example above, acme.dita2xHtmlwrapper is the name of the target. This will help to differentiate between your custom targets and the IXIASOFT targets.

Add the required dependencies:

<target name="acme.dita2xHtmlwrapper" depends="default_dependencies, flatten, extract_LowRes_images">

The depends attribute defines the other targets on which this target depends. In the example above, there are dependencies on three custom targets:

default_dependencies: Prepares the execution environment by running a set of targets that:
- Set up properties that are specific to the job, i.e., to the execution of the transformation scenario
- Configure default values for some properties
- Loads the user parameters into Ant properties so that they can be used in Ant scripts
The default_dependencies *must* be present for all transformation targets.
flatten: Prepares the content for the transformation by flattening the directory structure. This is required for branched maps, which contain objects in the Authoring cycle and objects in the Published cycle. The flatten target combines these objects in a single directory so that the DITA-OT can access the source files to transform.
Note: The flatten target has no impact on non-branched content, so you can specify it even if you do not have branched content at this point. This ensures that you don't have to add this target later on should you branch your content.
extract_LowRes_images: Prepares the content for the transformation by extracting the images in LowRes format, if available, instead of the default format. This target ensures that the DITA Open Toolkit can read the image files.

Working with dependencies

When a target is executed, it first calls the targets specified with the depends property, in the order they appear (from left to right).

Note: A target specified with the depends property can be executed earlier if an earlier target depends on it. For more information, see the Apache documentation at https://ant.apache.org/manual/targets.html.

Configure properties that are specific to this job:
```
   ...
   <property name="outgen.job.build.filename" 
             location="${outgen.job.dir}/build.xml"/>
   <property name="outgen.job.build.template.filename" 
             location="${outgen.resources.dir}/job-build-template.xml"/>
   <property name="outgen.job.build.otlog.filename" 
             location="${outgen.job.ot.log.dir}/${outgen.job.source.name.noext}.ot.log"/>
```
Since multiple jobs can be running at the same time, you must set some properties per transformation target so that they do not conflict between jobs. In the example above, the following properties are set:
- outgen.job.build.filename: Path and file name of the build.xml file that will be created
- outgen.job.build.template.filename: Path and file name of the template used to create the build.xml file
- outgen.job.build.otlog.filename: Path and file name of the DITA-OT log file
Create the build script:
```
   ...
   <antcall target="ot_build_create"/>
   <antcall target="ot_build_add_ditaval_ifpresent"/>
   <antcall target="ot_build_clean_ot_temp"/>
   <update-ot-build-file buildfile="${outgen.job.build.filename}">
      <param name="transtype" value="xhtml"/>
      <param name="args.rellinks" value="nofamily"/>
   </update-ot-build-file>
```
IXIASOFT CCMS provides targets to help you create and configure the build.xml file required by the DITA-OT when generating the output. The example above uses the following targets:
- ot_build_create: Creates the build.xml OT file based on the template file specified
- ot_build_add_ditaval_ifpresent: If the user specified a ditaval file when generating the output, sets the DITA-OT args.filter parameter to the value of the ditaval file in the build.xml file
- ot_build_clean_ot_temp: Sets the DITA-OT clean.temp parameter in the build.xml file to the value of the outgen.job.clean.ot.temp property
IXIASOFT CCMS also provides the update-ot-build-file target, which lets you update the OT build file to specify other parameters. In the example above, it is used to set the following parameters in the build.xml file:
- transtype to xhtml: Mandatory parameter that specifies the transformation type
- args.rellinks to nofamily: Optional parameter specifying that parent, child, next, and previous links are not included in the HTML output. Only reltable links will be included.
Each transtype may have its own set of parameters that must be defined in the build.xml file. For the list of all DITA Open Toolkit Ant parameters, see the DITA Open Toolkit documentation at the following location:
```
%OutputGenDir%/data/DITA-OT1.8.5/doc/index.html
```
Run the build script:
```
   ...
   <antcall target="dita_startcmd_ot_build"/>
```
The next step is to call the dita_startcmd_ot_build target, which is the target that calls the DITA-OT and runs the build script.
For more information about how the IXIASOFT Output Generator calls the DITA-OT, see Calling the DITA Open Toolkit from the IXIASOFT Output Generator.

Clean up the DITA-OT output directory (outputdir) folder:

   ...
   <antcall target="clean_ot_output"/>
</target>

After the DITA-OT transformation is completed, IXIASOFT Output Generator then cleans up the files by calling the clean_ot_output target, which removes all unnecessary files left over by the DITA Open Toolkit in the output directory before it zips the output and returns it to the end user.

The final target might look as follows:

<!-- New target with required dependencies -->
<target name="acme.dita2xHtmlwrapper" depends="default_dependencies, flatten, extract_LowRes_images">

   <!-- Configure job-specific properties -->
   <property name="outgen.job.build.filename" 
             location="${outgen.job.dir}/build.xml"/>
   <property name="outgen.job.build.template.filename" 
             location="${outgen.resources.dir}/job-build-template.xml"/>
   <property name="outgen.job.build.otlog.filename" 
             location="${outgen.job.ot.log.dir}/${outgen.job.source.name.noext}.ot.log"/>

   <!-- Create the build script -->
   <antcall target="ot_build_create"/>
   <antcall target="ot_build_add_ditaval_ifpresent"/>
   <antcall target="ot_build_clean_ot_temp"/>

   <update-ot-build-file buildfile="${outgen.job.build.filename}">
      <param name="transtype" value="xhtml"/>
   </update-ot-build-file>

   <!-- Run the build script -->
   <antcall target="dita_startcmd_ot_build"/>

   <!-- Clean up the OT build files -->
   <antcall target="clean_ot_output"/>
</target>