Migrate and Manage DITA-OT Publishing Scenarios

You can easily recreate your publishing scenarios configured in legacy DITA Open Toolkit (DITA-OT) in DITA-OT Cloud.

There are differences in how you configure publishing scenarios in each DITA-OT integration. Before you proceed review them in this table.

Major Differences Between Legacy DITA-OT and DITA-OT Cloud Publishing Scenario Configuration


	DITA-OT Legacy	DITA-OT Cloud
Browser compatibility	Mozilla Firefox only	Mozilla Firefox and Google Chrome™
Selecting a toolkit	Select a major toolkit version, select a toolkit, and select the build.xml file to run	Select a toolkit only
Selecting a custom plugin	Select appropriate plugins from a list	Ensure the plugins are included in whichever toolkit is needed
Referring to a file stored in the CCMS	Use the full URI to reference the locally stored file	Ensure the files are included in whichever toolkit is needed
Setting DITA-OT parameters	No difference	Both `transtype` and `args.filter` are configured by default in new scenarios. Remove or edit them as needed. Add any additional parameters that are needed for your publishing scenario.
Setting parameters for Antenna House rendering engine	Specify the pdf.formatter, axf.cmd, and axf.path parameters	For a DITA Open Toolkit that uses both Antenna House and FOP, include the pdf.formatter parameter in your publishing scenario to indicate the formatter to use, or if you want the option to select the formatter at the time of publishing. If you have more than one PDF formatter available in a toolkit, and you don't specify this parameter, the DITA-OT publishing uses FOP by default.
Setting parameters for custom fonts or other custom files	Specify the full database path in the CCMS	Use the Toolkit file picker option to specify the location of a custom font or other custom file within the toolkit folder.

DITA-OT Cloud Publishing Scenario Example

This example illustrates the publishing scenario settings you might use if you publish DITA to Microsoft Word with the publicly available com.elovirta.ooxml plugin. The scenario includes custom DOTX templates, which are included in the toolkit folder.

DITA-OT Cloud parameters example screen shot — Figure 1. DITA to Word Publishing Scenario Configuration

custom files in a dita open toolkit — Figure 2. Toolkit Example for Custom Template Files.
The custom Word templates are located in the WordTemplates folder.

Migrate Publishing Scenarios

You can easily recreate your publishing scenarios configured in legacy DITA-OT and use them for DITA-OT Cloud publishing.To complete this procedure, you need to be an Administrator in Heretto CCMS.

Open a legacy DITA-OT publishing scenario

Open Heretto CCMS in the Mozilla Firefox browser.
Note:
The Plugins interface is available only in Mozilla Firefox.
In the top-left corner, click the Main Menu and go to Plugins > DITA Open Toolkit.
In the Scenarios area, click the scenario you want to migrate.

Tip:
Keep the scenario open so you can refer to the settings as you recreate this scenario in DITA-OT Cloud.

Create a new DITA-OT Cloud publishing scenario

Open Heretto CCMS in a new window in Google Chrome™ or Mozilla Firefox.
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 transtype parameter to the same values as the legacy publishing scenario.

Tip:
We recommend using the Option type if you want to configure more than one transtype value, and the String type if you need to configure only one transtype value.
Keep or remove the args.filter parameter, as needed.

Note:
A default new publishing scenario is configured so that a user can select a DITAVAL every time they publish.

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 4. 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 5. 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 7. 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 8. Disabled publishing scenarios are not visible in the publishing interface
- To enable a disabled publishing scenario, select Enable.
  Figure 9. 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