Login
Home CMS Documentation Home CMS 10 DITA Processing Pipeline DITA-Related Special Topics Integrating Custom DTDs

Integrating Custom DTDs

Prerequisites:
  • Ensure the Custom DTD Root Asset Folder is specified in Administration > DITA > Setup. See Defining DITA Root and DTD Folders for details.

  • Prepare the custom DTDs and any files they reference (such as .ent and .mod files) for upload to the Custom DTD Root Asset Folder in the CMS Assets Manager. If the CMS upload process cannot locate the dependent files, the uploader will flag them as errors.

    Validate all DTD files you want to integrate before uploading, and ensure the DTD folder structure on your local file system will match the structure being uploaded to the CMS. You can do this by compressing all the DTDs and their dependencies to a .zip package. If the dependent files already reside within the custom DTD folder, you can upload the single DTD without creating the .zip package.

    Important
    If your custom DTDs reference stock DTDs from the DITA-OT, ensure you include the stock ones in the package. Otherwise, your custom DTDs will be unable to locate them in the CMS Assets Manager.

  • If DITA-OT version 3.1+ is installed, ensure the Skip DTD Denormalization checkbox is cleared on your DITA publishing target. See Configuring Post-Publish Content Processor for details.
  • If DITA-OT version 3.0 or below is installed:
    • You must have user group permissions to configure DITA.
    • Package all your custom DTDs,and any dependent files as a DITA-OT plugin. This prerequisite is in addition to packaging the DTDs within a .zip file. See DITA-OT: Creating Custom Plug-ins for details about custom plugins.
    • Ensure the Skip DTD Denormalization checkbox is selected on your DITA publishing target to prevent DTD denormalization/removal from being carried out during DITA post-publish processing.
  • If CMS 10.6.308–10.6.342 is installed, you must have system administrator permissions to access the CMS server to recycle the CMS application pool.
Tip
See OASIS DITA 1.3 DTD coding requirements for details about DTD specifications and constraints.

You can integrate custom DTDs directly in the CMS platform without packaging them as a DITA-OT plugin. After uploading and checking in the DTDs to the designated Custom DTD Root Asset Folder in the CMS Assets Manager, they will be processed and integrated into the CMS.

The CMS primarily uses the Custom DTD Root Asset Folder to validate the custom DTD schemas during the upload and check-in process. Once your custom DTDs are integrated, you can upload, check in, and run DITA publishing pipeline processing on the DITA assets that reference them. If you intend to edit these DITA assets in an XML editor like Fonto or Oxygen Web Author, this will require further configuration to the editor.

Custom DTD integration differs depending on the DITA-OT version you install. Follow the steps that correspond with your DITA-OT version.

DITA-OT 3.1+ Steps

To integrate custom DTDs in the CMS with DIA-OT 3.1+:
  1. Navigate to your custom DTD folder, then click New > Create New AssetNew Drop-down Button in the folder's Overview tab.
  2. Drag your DTD and any files your DTDs reference to the upload area, then click Upload.
  3. If you're uploading a .zip package, leave the default selections as is in the Zip Unpack Options dialog, and click Upload.

    Zip Unpack Options

    The CMS uploads the DTDS to the folder.
    Note
    After extracting and uploading your .zip package, the CMS creates a folder based on the package name. To ensure the folder structure matches the structure on your local file system, consider renaming the subfolder or moving the uploaded DTDs and dependencies out of the subfolder and then deleting it.
  4. Right-click the custom DTD folder, then click Check In > Folder and Children to check in all your newly uploaded DTDs.

    Check In Custom DTDs

  5. Navigate to the Internet Information Services (IIS) Manager on the CMS server, then recycle the CMS application pool.
    Version Notes: CMS 10.6.378 vs. CMS 10.6.308–10.6.342
    This step only applies to CMS 10.6.308–10.6.342. If you have CMS 10.6.378, skip this step.

The CMS processes and integrates your custom DTDs.

Task Troubleshooting: If you receive the error message, Cannot locate custom DTD, this indicates the custom DTD has not been successfully integrated. For example, the full error message is similar to this:

Cannot locate custom DTD at 'articleDetail.dtd' with public id '-//CCS//DTD DITA Article Detail//EN. 
Please make sure DTD root is configured, custom DTDs are uploaded, and the uploaded DTD folder structured 
matches the structure on your locale file system for this package.
If you encounter this error, check the following:
  1. Verify the prerequisites have been met. Double-check that all necessary requirements have been fulfilled.
  2. Ensure all your DTDs and dependent files are valid.
  3. Ensure you upload and check in the DTDs and all their dependencies, including any referenced stock DITA-OT DTD files, to your designated custom DTD folder. If the error message indicates a file with an extension such as .ent or .mod cannot be located, this indicates referenced files are missing from the custom DTD folder.
  4. Version Notes: CMS 10.6.308–10.6.342
    If CMS 10.6.308–10.6.342 is installed, remember to recycle the CMS application pool after uploading and checking in the custom DTDs.

    Also, if an administrator has changed the Custom DTD Root Folder ID to a different folder ID in Administration > DITA > Setup, the application pool will need to be recycled.

If you encounter further issues or have questions, contact Ingeniux Support.

Next Steps:

To confirm your DTDs have been fully integrated, run one or more of the following tests:

  • Upload DITA assets that reference the custom DTD.
  • Check in the DITA assets that reference the custom DTD.
  • Run a DITA preview on DITA assets that reference the custom DTD to verify the DITA-OT processes the custom DTD successfully.

DITA-OT 3.0 and Below Steps

The custom DTD integration upload feature is incompatible with DITA-OT versions 3.0 and earlier. Uploading the custom DTDs to the Custom DTD Root Asset Folder allows the CMS to validate DITA assets that reference the custom DTDs on upload and check in, but the uploaded DTDs will not be integrated into the DITA-OT. To integrate your custom DTDs into DITA-OT 3.0 or earlier, package them as a DITA-OT plugin and deploy the plugin to the DITA-OT on the CMS in addition to uploading them to the Assets Manager.

Note
You can deploy the custom DTD plugin to the installed DITA-OT on the CMS, or, if you have your own DITA-OT version that already has the custom DTD plugin deployed, you can install that DITA-OT version directly in the CMS.
To integrate custom DTDs in the CMS:
  1. Navigate to Administration > DITA > Setup.
  2. Follow the steps that correspond with your preferred custom DTD integration method:

    • Upload your custom DTD plugin to the installed CMS DITA-OT.

      1. Click Add Plugin in the DITA Open Toolkit Setup area.
      2. Drag the plugin to the upload area in the Upload DITA Open Toolkit Plugins dialog.
      3. Click Upload.

      The CMS installs the plugin and integrates the custom DTD files.

    • Upload the custom DITA-OT version that includes the custom DTD plugin.

      1. Click the Version drop-down list in the DITA Open Toolkit Setup area, then select the Install Custom DITA-OT option.
      2. If the Redeploy DITA Open Toolkit dialog displays, click Yes to confirm you want replace the installed DITA-OT version with your custom version.

      The CMS instealls the DITA-OT along with the plugin that integrates the custom DTDs.

  3. Follow the DITA-OT 3.1+ Steps to upload your custom DTDs to the Custom DTD Root Asset Folder.

    This will allow the CMS to validate the custom DTD schemas within the Assets Manager. If the DTDs are not uploaded to this folder, you will encounter the Cannot locate custom DTD error when uploading and checking in assets that reference the custom DTDs.

Task Troubleshooting: If you receive the error message, Cannot locate custom DTD, this indicates the custom DTD has not been successfully integrated. For example, the full error message is similar to this:

Cannot locate custom DTD error
Cannot locate custom DTD at 'articleDetail.dtd' with public id '-//CCS//DTD DITA Article Detail//EN. 
Please make sure DTD root is configured, custom DTDs are uploaded, and the uploaded DTD folder structured 
matches the structure on your locale file system for this package.
If you encounter this error, verify the following:
  1. Verify the prerequisites have been met. Double-check that all necessary requirements have been fulfilled.
  2. Ensure all your DTDs are valid, and verify your custom DTD plugin is functioning properly.
  3. If you have installed a custom DITA-OT version, ensure your DITA-OT is functioning properly. See DITA Open Toolkit Architecture for details about the processing structure and other factors.
  4. Ensure you upload and check in the DTDs and all their dependencies, including any referenced stock DITA-OT DTD files, to your designated custom DTD folder. If the error message indicates a file with an extension such as .ent or .mod cannot be located, this indicates referenced files are missing from the custom DTD folder.
If you encounter further issues or have questions, contact Ingeniux Support.

Next Steps:

To confirm your DTDs have been fully integrated, you can run one or more of the following tests:

  • Attempt to upload DITA assets that reference the custom DTD.
  • Attempt to check in the DITA assets that reference the custom DTD.
  • Attempt to run a DITA preview on DITA assets that reference the custom DTD to verify the DITA-OT processes the custom DTD successfully.