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	DITA-OT Cloud always looks for the Antenna House components in an /ah-formatter folder in the toolkit folder. There's no need to declare the PDF formatter or its location.
Setting parameters for custom fonts or other custom files	Specify the full database path in the CCMS	Specify the path within the toolkit folder. For example, for custom fonts, use custom-fonts/myCustomFont.ttf. For a custom file, use a path that specifies the custom folder location and the file name.

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.
Add any other parameters your publishing scenario may need.
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.

custom template string example — Figure 5. String used to specify a file in custom plugin.
Some custom plugins may have specific files that are needed when publishing. You can refer such a file with a string parameter type. Note that the path is set from the root of the DITA-OT, not the CCMS.

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 6. 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 a file selector for a parameter. As a result, users can select a file at the time of publishing in the publishing scenario. For example, a DITAVAL file or a custom image for the PDF cover.

File reference

Use the File reference parameter type to set a path to a file located inside a toolkit. The value cannot be edited while publishing.

Important:

There's a known issue related to this option. Please do not use it until we resolve the issue. As a workaround, you can use the String parameter type to specify a file located in a toolkit.

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.