home

Integrations

Content ManagementWeb DeploymentIntegrations
Content ManagementWeb DeploymentIntegrations

Show Contents

Show Page Sections

thumbnailIntegrations

Migrating to DITA-OT Cloud Publishing

Migrating from Legacy DITA-OT to DITA-OT Cloud

If you haven't read it yet, before proceeding review the Read Me to understand major differences between legacy DITA Open Toolkit (DITA-OT) and DITA-OT Cloud integrations.

Migration Scenarios

You use a default DITA Open Toolkit (DITA-OT) other than 2.5.4 or 3.6.1

Default 2.5.4 and 3.6.1 toolkits are by default installed in the system.

Important: DITA-OT Cloud only supports toolkit versions 2.5.4 or higher.

  1. Download DITA Open Toolkits from Heretto CCMS: Download DITA Open Toolkit Resources from Heretto CCMS.

  2. Migrate Publishing Scenarios.

You use custom plugins

  1. Download DITA Open Toolkit Resources from Heretto CCMS.

  2. Add Custom Plugins to DITA Open Toolkit.

  3. Compress the Custom DITA Open Toolkit into a ZIP File.

  4. Add a DITA-OT to Heretto CCMS.

  5. Migrate Publishing Scenarios.

You use custom fonts

  1. Contact your Customer Success Manager or our support team to have the fonts downloaded.

  2. Download DITA Open Toolkit Resources from Heretto CCMS.

  3. Add Custom Fonts to DITA Open Toolkit.

  4. Compress the Custom DITA Open Toolkit into a ZIP File.

  5. Add a DITA-OT to Heretto CCMS.

  6. Migrate Publishing Scenarios.

You use Antenna House (AH)

  1. Contact your CSM or our support team to have the AH application and license downloaded.

  2. Download DITA Open Toolkit Resources from Heretto CCMS.

  3. Add Antenna House Formatter to DITA Open Toolkit.

  4. Compress the Custom DITA Open Toolkit into a ZIP File.

  5. Add a DITA-OT to Heretto CCMS.

  6. Migrate Publishing Scenarios.

You use a combination of the above

You can combine different components in the migration process. The general DITA-OT Cloud rule is that any components needed for publishing, for example Antenna House, custom fonts, or custom plugins, need to be embedded in the toolkit. If you use multiple components, update the toolkit with all the needed components and then compress your toolkit.

Download DITA Open Toolkit Resources from Heretto CCMS

Download DITA Open Toolkits (DITA-OT) and plugins that you need to migrate from the deprecated Plugins interface. In DITA-OT Cloud, any components needed for publishing, like Antenna House (AH), custom fonts, or custom plugins, need to be embedded in the toolkit.

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

The Plugins interface is deprecated and will eventually be disabled. We recommend downloading and backing up all toolkit resources, especially custom toolkits and plugins.

Download any default or custom DITA Open Toolkits from Heretto CCMS

  1. Open Heretto CCMS in Mozilla Firefox and sign in.
  2. In the top-left corner, click the Main Menu and go to Plugins > DITA Open Toolkit.
  3. In the Available DITA Open Toolkits area, click any toolkits you need to migrate to DITA-OT Cloud.

    The clicked toolkits are saved to your machine.

Download any plugins from Heretto CCMS

  1. Scroll down to the DITA-OT Plugins area and click any plugins you need to migrate to DITA-OT Cloud.

    The clicked plugins are saved to your machine.

Add Custom Plugins to DITA Open Toolkit

Custom plugins may include transformation (publishing) customizations, document type specializations, or both. In this procedure, we are assuming that your custom plugin(s) are ready to be added to a DITA Open Toolkit (DITA-OT). For DITA-OT Cloud publishing, all custom DITA-OT plugins need to be included in your toolkit.

If you do not have the skills required to prepare a custom plugin, you can learn at dita-ot.org or we can recommend a partner who provides DITA-OT customization services.

This document doesn't explain how to create custom plugins.

  1. Unzip the toolkit you want to customize.
  2. In the unzipped toolkit, navigate to the plugins folder.
  3. Copy any custom plugins into that folder.
    Figure 1. Example DITA-OT Plugins Folder
    DITA Open Toolkit Plugins Folder

Add Custom Fonts to DITA Open Toolkit

Fonts in a toolkit are available only to that DITA-OT and the related publishing scenario. If you have multiple toolkits that need to use the same fonts, you need to add those fonts to each DITA-OT.
  1. Unzip the toolkit you want to customize.
  2. In the unzipped toolkit, navigate to the root of the toolkit folder.

    The root of a toolkit folder is, for example, dita-ot-3.6.1.

  3. Create a new folder called custom-fonts.
    Important: Ensure that the folder name custom-fonts is only lower case.
  4. Add font files to the custom-fonts folder.

    You can use any font file type you want, for example, TFF, OTF, WOFF. There is no restriction on the number of font files you can add.

    Figure 2. dita-ot-3.6.1 Root Folder with a custom-fonts Folder
    custom-fonts folder in DITA Open Toolkit folder

In your DITA-OT plugins, be sure to change any references to custom font files to use the new location in your toolkit directory. If you use Antenna House, you may need to adjust the font settings to also use the new location.

Add Antenna House Formatter to DITA Open Toolkit

Each default DITA Open Toolkit (DITA-OT) comes with a default Formatting Objects Processor (FOP) that converts content into the PDF output format. Antenna House (AH) Formatter is a custom, licensed formatter that is useful if you have complex pagination and page layout, publish PDF outputs to multiple languages, or need to specify different fonts for different locales.

Antenna House Formatter is licensed. If you need a license, contact your Customer Success Manager.

Important:

You need to use a Linux version of Antenna House. Other versions do not work with Heretto CCMS.

  1. Unzip the toolkit you want to customize.
  2. In the unzipped toolkit, navigate to the root of the toolkit folder.

    The root of a toolkit folder is, for example, dita-ot-3.6.1.

  3. Create a new folder called ah-formatter.
    Important: Ensure that the folder name ah-formatter is only lower case.
  4. Add the Antenna House components into the ah-formatter folder.

    Antenna House components include a number of folders, for example, bin, docs, etc, and files, for example, ReadMe.txt, run.sh.

    Important: Do not nest additional folders such as /usr. Put only the actual components in the ah-formatter folder.
  5. Add the Antenna House license file, AHFormatter.lic, to the ah-formatter/etc folder.
    An example folder structure for formatter

Compress the Custom DITA Open Toolkit into a ZIP File

Your custom DITA Open Toolkit (DITA-OT) needs to be compressed into a ZIP file. Before compressing the toolkit, give it a meaningful name. We recommend adding _embed, the date of toolkit creation, or both to the folder name. All toolkits you upload to Heretto CCMS, need to have unique names.

  1. Give your toolkit folder a meaningful name.

    Consider providing the following information in the toolkit name:

    • The full toolkit name, for example, dita-ot-2.5.4.

    • The date of when the toolkit was created or added to Heretto CCMS. For example, dita-ot-2.5.4-aug-10-2022.

    • The word embedded or something similar to indicate that the toolkit contains custom plugins. For example, dita-ot-2.5.4-emb-aug-10-2022.

  2. Compress your folder into a ZIP format.

Add a DITA-OT to Heretto CCMS

Upload your custom DITA Open Toolkit (DITA-OT) ZIP file to Heretto CCMS so you can use it in publishing scenarios.

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

  1. In the top-left corner, click the Main Menu and go to DITA-OT.
  2. In the Toolkits section, click New toolkit.
  3. In the New Toolkit window, in the Toolkit name field, provide a name for the toolkit.
    Tip:

    To use the ZIP file name as the toolkit name, leave the Toolkit name field empty.

    Consider providing the following information in the toolkit name:

    • The full toolkit name, for example, dita-ot-2.5.4.

    • The date of when the toolkit was created or added to Heretto CCMS. For example, dita-ot-2.5.4-aug-10-2022.

    • The word embedded or something similar to indicate that the toolkit contains custom plugins. For example, dita-ot-2.5.4-emb-aug-10-2022.

  4. Click Choose file and select the DITA-OT ZIP package.
  5. Click Create.
    Note:

    Depending on its size and your internet connection, uploading a new toolkit may take a few minutes.

Once the upload completes, the new toolkit is listed in the Toolkits section.

Create a publishing scenario with the DITA-OT that you uploaded. See Migrate Publishing Scenarios.

Last updated: May 29, 2023