Configure and Manage DITA-OT Publishing Scenarios

Users assigned the Administrator role in Heretto CCMS can configure and manage DITA Open Toolkit (DITA-OT) publishing scenarios in Heretto CCMS. Any user with publishing permissions can use those publishing scenarios to generate output.

Create a DITA-OT Publishing Scenario in Heretto CCMS

DITA Open Toolkit (DITA-OT) publishing scenarios consist of two main building blocks: a DITA-OT and scenario parameters. You can use either a default or custom DITA-OT. Publishing scenarios are visible in the publishing interface to any user with publishing permissions.

To complete this procedure, you need to be an Administrator in Heretto CCMS.

Note:

This procedure explains how to get the most common DITA-OT publishing scenario configurations. For other configurations, see DITA-OT Parameters Options.

In the top-left corner, click the Main Menu and go to DITA-OT.
In the DITA-OT scenarios section, click New Scenario.
In the New scenario window that opens:
1. In the Scenario name field, add a meaningful name of your publishing scenario.
  The scenario name is visible in the publishing interface to any user with publishing permissions.
2. From the Toolkit name drop-down menu, select a DITA-OT that you want to use in this publishing scenario.

Set the required transformation type (transtype) parameter

Leave the Type field set to Option.
Leave the Name field set to transtype.
Optional: In the Display name field, add a meaningful name. For example, Output type.

If you leave the Display name field empty, the publishing scenario shows the actual parameter name.
In the Max selected items field, set the maximum number of output types a user can publish in one publishing job.
In the Options section, set the transformation type(s):
1. In the Name field, provide a valid DITA-OT transformation type.
  
  By default, the CCMS suggests pdf, html5, xhtml. When publishing, the system defaults to the first transformation type in the Options section. The transformation type value(s) must correspond with the transformation type(s) configured in the DITA-OT (toolkit) you selected for this scenario.
  Important:
  If you have complex publishing requirements that involve custom plugins, fonts, and Antenna House (AH), avoid creating a single toolkit or publishing scenario for multiple output types as it can slow down the publishing process. See Best Practices for Creating Custom Toolkits.
2. Optionally, in the Display name fields, add meaningful names for the transformation type(s).
  
  If you leave the Display name fields empty, the publishing interface defaults to values in the Name fields.

Set optional filtering with a DITAVAL

Scroll down to the next Parameter section.
In the Type drop-down menu, leave the Type field set to File picker.
Leave the Name field set to args.filter.
Optional: In the Display name field, add a meaningful name for args.filter parameter, for example, Ditaval.

If you leave the Display name field empty, the publishing scenario shows the parameter name.
Leave the User settable option selected.

For Antenna House (AH) users only: You need to specify the AH formatter as the PDF formatter in the publishing scenario. If you don't specify AH, the CCMS defaults to FOP.

Click New parameter.
Leave the Type field set to String.
In the Name field, add pdf.formatter.
Optional: In the Display name field, add a meaningful name for the pdf.formatter parameter, for example, PDF Formatter.

If you leave the Display name field empty, the publishing scenario shows the parameter name.
Leave the User settable option cleared.
In the Enter value field, ad ah.
Optional: Add additional parameters by clicking New parameter and specifying parameter values.

For more information about parameters and parameter values, see https://www.dita-ot.org/dev/parameters/parameters_intro.html.
In the New scenario window, click Create.

Your DITA-OT Cloud publishing scenario is listed in the DITA-OT scenarios section in the Administration interface from where you can manage it. All users with publishing permissions can use the scenario from the publishing interface to publish content.

DITA-OT Parameters Options

DITA Open Toolkit (DITA-OT) offers numerous parameters that you can set in a publishing scenario. The only parameter required for DITA-OT publishing is transtype (transformation type). When creating a DITA-OT publishing scenario, you define a parameter, parameter value(s), and parameter types.

For more information about DITA-OT parameters and parameter values, see https://www.dita-ot.org/dev/parameters/parameters_intro.html.

DITA-OT Parameter Types in Publishing Scenarios

When configuring a DITA-OT publishing scenario in Heretto CCMS, for each parameter, like transtype or args.filter, you specify a parameter type. You can choose from a few parameter types.

String

Use the String parameter type to set a specific value for a specific parameter in the publishing scenario. For example, you can use it to set a fixed transtype or DITAVAL for a scenario. If you are using custom plugins, you can also use the String parameter type to refer to files in that plugin, for example templates or options files.

Figure 2. String Used to Set a Fixed DITAVAL.
With this setting, DITAVAL in the publishing scenario is always set to a specific DITAVAL and users can't change that in the publishing interface. You specify the DITAVAL by adding its universally unique identifier (UUID) in the Enter value field. See Get a Resource UUID.

Option

Use the Option parameter type to set multiple values for a parameter that has more than one value. As a result, users are presented with multiple options in the publishing scenario. The default option is the one listed first.

Additionally, you can specify the maximum number of options users can select in one publishing job.

Option parameter type used to set four output types — Figure 3. Option Used to Set Four Transtypes.
With this setting, the publishing scenario enables users to get from one to four output types in one publishing job. If a user selects no option, the scenario defaults to the first output type, here `pdf`.

File picker

Use the File picker parameter type to set up a file selector for a parameter. When configured, users can select a file in the CCMS at the time of publishing. For example, a DITAVAL file or a custom image for a PDF cover.

File reference

The File reference parameter type is being retired. To set a path to a file located inside a toolkit, use the Toolkit file picker parameter type.

Toolkit file picker

Use the Toolkit file picker parameter type to set a path to a file located inside an uploaded toolkit. This parameter uses an absolute path, meaning that it specifies the location of a file or folder from the root folder of the toolkit.

Important:

Currently, the Toolkit file picker option is only compatible with toolkits uploaded to the CCMS on February 14, 2024 and later. We recommend that you reupload any toolkits you want to use with this option. If you attempt to use this option with a toolkit uploaded before this date, an error message will prompt you to reupload the toolkit.

the toolkit file picker option used to refer to a Microsoft Word template file template.dotx inside a toolkit — Figure 5. Toolkit file picker used to specify a file in a plugin.
Some plugins may have specific files that are needed when publishing. You can refer such a file with the toolkit file picker parameter type. Here, the publishing scenario refers to a Microsoft® Word template file template.dotx. Because parameters added with the Toolkit file picker option are visible in the publishing interface, we recommend adding a meaningful display name. The Name and User settable options should remain empty.

Disable or Re-enable a DITA-OT Publishing Scenario

Any user with publishing permissions can use publishing scenarios. If you want to prevent users from using a publishing scenario but would like to keep it for reference, disable the scenario. You can re-enable a disabled scenario at any point in time.

To complete this procedure, you need to be an Administrator in Heretto CCMS.

In the top-left corner, click the Main Menu and go to DITA-OT.
Hover over a publishing scenario and click More actions .
From the context menu, select an action:
- To disable a publishing scenario, select Disable.
  Figure 6. Disabled publishing scenarios are not visible in the publishing interface
- To enable a disabled publishing scenario, select Enable.
  Figure 7. Enabled publishing scenarios are visible in the publishing interface

A disabled publishing scenario is still listed in the Administration interface and Administrators can modify and re-enable them. Disabled scenarios are not listed in the publishing interface and so can't be used to publish content

Delete a DITA-OT Publishing Scenario

You can delete redundant publishing scenarios. Deleted scenarios can't be restored. If you want to prevent users from using a publishing scenario but are unsure if the scenario should be deleted, disable the scenario. Disabled scenarios can't be used for publishing but are still available in the DITA-OT scenarios section to Administrators.

To complete this procedure, you need to be an Administrator in Heretto CCMS.

Warning:

This action is irreversible. You cannot restore deleted publishing scenarios.

Important:

Deleting a publishing scenario does not delete or remove the DITA Open Toolkit that was associated with the scenario.

In the top-left corner, click the Main Menu and go to DITA-OT.
Hover over a publishing scenario and click More actions .
From the context menu, select Delete.
If prompted, confirm the deletion.

The scenario no longer exists in Heretto CCMS. It can't be restored.

Gretyl's Portal

Heretto Help

Configure and Manage DITA-OT Publishing Scenarios

Create a DITA-OT Publishing Scenario in Heretto CCMS

DITA-OT Parameters Options

DITA-OT Parameter Types in Publishing Scenarios

Disable or Re-enable a DITA-OT Publishing Scenario

Delete a DITA-OT Publishing Scenario

Footer Section

Our Support Team is here to help