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/manual/. 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.bat file and build.properties files
Execute build.bat
Clean up the files

There are two essential directories when creating a transformation scenario:

Input directory: When IXIASOFT CCMS 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 or a map that includes content from different cycles (authoring, published, localization), you must call the flatten target before modifying the source files. The flatten target will copy all the 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 (if using CCMS Desktop) or saved to the app server for later download (if using CCMS Web). 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, resolve_container_keyref, extract_LowRes_images">
	<echostart>acme.dita2xHtmlwrapper</echostart>

	<ot_build_add_ditaval_ifpresent/>
	<ot_build_clean_ot_temp/>

	<ot_build_set_parameter name="transtype" value="xhtml"/>

	<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.dita2xHtmlwrapper</echoend>
</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.
Note: When a target is executed, it first calls the targets specified with the depends property, in the order they appear (from left to right).
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.
Add the ditaval file:
```
<ot_build_add_ditaval_ifpresent/>
```
If the user specified a ditaval file when generating the output, this macro sets the DITA-OT args.filter parameter to the value of the ditaval path and filename in the build.properties file.
Clean out the job's temp folder after the output is complete:
```
<ot_build_clean_ot_temp/>
```
This macro sets the DITA-OT clean.temp parameter in the build.properties file to the value of the outgen.job.clean.ot.temp property
Set the transformation type:
```
<ot_build_set_parameter name="transtype" value="xhtml"/>
```
This transtype must correspond to the transtype defined for a plugin in the DITA-OT being used for the output.
Configure properties that are specific to this job:
```
<dita_startcmd_ot_build/>
```
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. The dita_startcmd_ot_build macro sets the following properties:
- outgen.job.ot.dita.command: Sets the location of the dita command within the DITA-OT
- outgen.job.ot.command.logfile: Sets the name of the log file
- outgen.job.ot.command.propertyfile: Specifies that the property file to be used is named build.properties and is located in the outgen.job.dir
- outgen.job.ot.command.input: Specifies the input, usually the selected ditamap
- outgen.job.ot.command.output.dir: Specifies the output location
- outgen.job.ot.command.format: Specifies the transtype
- outgen.job.ot.command.dita.dir: Specifies the DITA-OT to be used
- outgen.job.ot.command.dita.temp.dir: Specifies the temp directory for the job
- outgen.job.ot.properties:
Record the build properties in the build.properties file:
```
<echoproperties destfile="${outgen.job.ot.command.propertyfile}">
	<propertyset>
		<propertyref prefix="outgen.job.ot.properties."/>
		<mapper type="glob" from="outgen.job.ot.properties.*" to="*"/>
	</propertyset>
</echoproperties>
```
This is also part of the dita_startcmd_ot_build macro. These properties can be specified in the target or selected by the user on the Generate Output dialog/page.
For the list of all DITA Open Toolkit Ant parameters, see the DITA Open Toolkit documentation at the following location:
```
%OutputGenDir%/data/dita-ot-2.5.4/doc/parameters/index.html
```

Create the build.bat file:

The dita_startcmd_ot_build macro also constructs the build.bat file from some of the properties listed in step 7:

<property name="outgen.job.ot.batchfile.content" ¶
value="&quot;${outgen.job.ot.dita.command}&quot; ¶ 
-i &quot;${outgen.job.ot.command.input}&quot; ¶ 
-f ${outgen.job.ot.command.format} ¶ 
-o &quot;${outgen.job.ot.command.output.dir}&quot; ¶ 
-propertyfile &quot;${outgen.job.ot.command.propertyfile}&quot; -v"/>

Note: The ¶ symbol indicates a line break inserted in the code sample for clarity and readability. In an actual build.bat file, there are no line breaks.

Run build.bat or build.sh.

Depending on the detected operating system, the dita_startcmd_ot_build macro launches one of two other macros:

<switch value="${outgen.os.family}">
	<case value="windows">
		<dita_startcmd_ot_build_windows/>
	</case>
	<case value="unix">
		<dita_startcmd_ot_build_linux/>
	</case>
	<default>
		<fail message="No DITA command for the OS family ${outgen.os.family}"/>
	</default>
</switch>

The dita_startcmd_ot_build_windows macro:

<macrodef name="dita_startcmd_ot_build_windows">
	<sequential>
		<echostart>dita_startcmd_ot_build_windows</echostart>

		<property name="outgen.job.ot.batchfile" location="${outgen.job.dir}/build.bat"/>

		<!-- Do not indent the lines inside the "echo" element -->
		<echo file="${outgen.job.ot.batchfile}">@echo off
${outgen.job.ot.batchfile.content}</echo>

		<exec executable="cmd.exe" output="${outgen.job.ot.command.logfile}" ¶
		      append="true" dir="${outgen.job.dir}" failonerror="false" ¶
			  resultproperty="outgen.job.ot.return.code">
			<arg value="/c"/>
			<arg value="${outgen.job.ot.batchfile}"/>
			<arg value="2&gt;&amp;1"/>
		</exec>

		<echoend>dita_startcmd_ot_build_windows</echoend>
	</sequential>
</macrodef>

The dita_startcmd_ot_build_linux macro:

<macrodef name="dita_startcmd_ot_build_linux">
	<sequential>
		<echostart>dita_startcmd_ot_build_linux</echostart>

		<property name="outgen.job.ot.batchfile" location="${outgen.job.dir}/build.sh"/>

		<!-- Do not indent the lines inside the "echo" element -->
		<echo file="${outgen.job.ot.batchfile}">#!/bin/bash
export JAVA_HOME=${outgen.job.ant.java.home}
${outgen.job.ot.batchfile.content}</echo>

		<chmod file="${outgen.job.ot.dita.command}" perm="755"/>
		<chmod file="${outgen.job.ot.batchfile}" perm="755"/>
		<exec executable="${outgen.job.ot.batchfile}" output="${outgen.job.ot.command.logfile}" ¶
		      append="true" dir="${outgen.job.dir}" failonerror="false" ¶
			  resultproperty="outgen.job.ot.return.code">
			<arg value="2&gt;&amp;1"/>
		</exec>

		<echoend>dita_startcmd_ot_build_linux</echoend>
	</sequential>
</macrodef>

Clean up the DITA-OT output directory (outputdir) folder:
```
<clean_ot_output/>
```
Returning to the original acme.dita2xHtmlwrapper target, after the DITA-OT transformation is completed, CCMS Output Generator then cleans up the files by calling the clean_ot_output macro. This removes all unnecessary files left over by the DITA Open Toolkit in the output directory before it zips the output and either returns it to the end user (in CCMS Desktop ) or saves it to the app server (in CCMS Web).