Login
Home CMS Documentation Home CMS 10 DITA Processing Pipeline DITA-Related Special Topics Enabling Aliases for Custom DITA Types

Enabling Aliases for Custom DITA Types

Prerequisites:
  • CMS 10.6.492 must be installed. See CMS Statistics to check your version.
  • Users must have system administrator permissions to the CMS server.
  • Custom DTDs must be integrated into your CMS. See Integrating Custom DTDs for details.
  • Document configuration requirements by reviewing your custom DTDs and identifying these items:
    • DTD Public IDs.
    • Custom map elements, including any map elements that contain links or function similarly to <topichead>, <topicset>, or <topicgroup>.
  • DITA assets using custom DTDs must reference the DTD via public ID in <!DOCTYPE> declaration.

Configure DitaAliasSchemaConfigurations.json to enable alias creation and management for DITA assets that use custom document type definitions (DTDs).

Review these key terms before configuring DitaAliasSchemaConfigurations.json:

DTD Public ID

Standardized, unique strings used in <!DOCTYPE> declarations that identify the DTD version, document type, and owner. Public IDs ensure consistent XML validation and enable DTD location resolution via catalogs.

Example <!DOCTYPE> declaration with DTD public ID for a standard OASIS DITA 1.3 topic type:

DOCTYPE declaration with public ID
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
See OASIS DITA 1.3 DTD public identifiers for details about public IDs.
Map container

DITA map elements such as <topichead>, <topicset>, and <topicgroup> that act as containers within the map hierarchy to define or group elements together.

See OASIS DITA 1.3 Map group elements for element details.
To configure alias support for DITA assets that use custom DTDs:
  1. Navigate to [Drive:]\[path-to-cms-site-instance]\App_Data\settings\.
  2. Open DitaAliasSchemaConfigurations.json in a text editor.
  3. Configure custom DTD public IDs using one or both settings:
    • Set DTDPublicIDs to enter the full public ID of custom DTDs requiring alias support.

      Example (replace with your public IDs):

      DTD public IDs
      "DTDPublicID": [
                  "-//Ingeniux//DTD DITA myTopic//EN",
                  "-//IGX//DTD DITA Custom Topic//EN",
                  "-//MyCorp//DTD DITA Composite//EN"
                  ],
    • Set DTDPublicIDPrefixes to enter public ID prefixes.

      The CMS registers any custom DTD with matching prefixes, enabling alias support for multiple DTDs sharing the same prefix without listing each full public ID.

      Example (replace "-//Ingeniux" with your prefixes):

      DTD public ID prefixes
      "DTDPublicIDPrefixes": [
                  "-//OASIS//DTD DITA",
                  "-//Ingeniux"
                  ],
  4. Configure DITAContainerElements to specify DITA map elements the CMS parses to determine linked content for aliases:

    • Set to false for elements containing references that require parsing to determine linked content (e.g., <topicref href="stylesheets/_presentations_/FormField_Label.xsl">) during alias creation and updates.

    • Set to true for elements without direct linking attributes (e.g., <topichead>, <topicset>, <topicgroup>) that do not require parsing during alias creation and updates.

    Example (add your DITA container elements):

    DITA container elements
    "DITAContainerElements": {
        "topicref": false,
        "part": false,
        "chapter": false,
        "appendix": false,
        "appendices": true,
        "topicsetref": false,
        "topichead": true,
        "topicset": true,
        "topicgroup": true
      },
  5. Configure DITAContainerSkippedForAlias to specify map group elements that will not generate DITA container aliases.

    Adding a DITA map element to this setting prevents the CMS from generating aliases for that element during alias creation and updates. The CMS continues creating and updating aliases for child elements nested within these elements, displaying them in the alias structure without their specified parent element.

    Example (add your skipped DITA container elements):

    DITA container elements
    "DITAContainerSkippedForAlias": [
        "topicset",
        "topicgroup"
      ]
  6. Save and close DitaAliasSchemaConfigurations.json.
  7. Recycle the CMS instance application pool:
    1. Open Internet Information Services Manager (IIS) and navigate to the CMS instance application pool.
    2. Right-click the application pool and click Recycle.

The CMS registers your configuration changes. Users can create and manage aliases for DITA assets using custom DTDs that match configurations in DitaAliasSchemaConfigurations.json. The CMS parses specified elements according to your configurations.

Task Troubleshooting: If the CMS does not register configuration changes or prevents alias creation for DITA assets that use custom DTDs, verify:

  • Custom DTDs are integrated into the CMS per prerequisites.
  • Settings match the public ID and DITA elements in your custom DTDs. Check out the DITA asset and review its public ID and elements in the Edit tab. Verify all aliases and applicable elements are processed and included for alias support.
  • DitaAliasSchemaConfigurations.json uses proper formatting with commas as delimiters between values. Compare your edited file to the original stock version if needed.
  • You saved DitaAliasSchemaConfigurations.json and recycled the CMS application pool.
Contact Ingeniux Support if issues persist.

Next Steps:

Verify configuration changes by creating aliases for DITA assets that use custom DTDs.

Verification tests include:

  • CMS creates aliases without throwing the DitaAliasSchemaConfigurations not found for Public ID error.
  • Elements parse correctly for link determination.
  • CMS skips appropriate DITA container elements during alias creation and generates aliases for the child elements.