DITA "Used By" Properties


The Used By tab displays on every asset item, including non-DITA assets. This tab contains information about DITA content that references the currently selected DITA or non-DITA asset.

For example, if a DITA topic includes a reference to the currently select image asset, then that The topic will display as a usage reference dependency in the Used By tab list of entries. Also, the image asset's Used By tab list entries will include the DITA map that references the DITA topic, as the linking relationship correlates to the image asset's hierarchical relationship structure (for example, the dependency route).

The term "usage reference" represents a DITA asset that is referencing another asset. This means the asset item corresponding with the Used By tab is the dependency being referenced by that DITA asset.

Version Notes: CMS 10.6.378 vs. CMS 10.6.308–10.6.342
Dependency functionality differs between CMS 10.6.378 and CMS 10.6.308–10.6.342.
  • In CMS 10.6.378, DITA asset Depends On dependencies are accounted for based on the DITA asset's latest content version and versions marked to publishing targets. In the Used By tab, usage references point to DITA assets that reference the currently selected DITA or non-DITA asset.

    For example, if a marked-for-publish DITA map version references the asset item corresponding with the Used By tab, a usage reference will be included for that map version in this tab.

    To filter Used By entries based on the referencing asset's content version, you can use the Dependency Version drop-down list.

  • In CMS 10.6.308–10.6.342, dependencies are only accounted for based on the current version of the DITA asset item. If you make and save changes to a DITA asset item's dependencies via the Edit tab, the Used By list entries update to reflect the new changes, no matter if the asset is checked in or out. If you mark an older version of the DITA asset item for publish, the CMS dependency system will not account for the dependencies in that version.

See CMS DITA Versioning Functionality for more details about CMS 10.6 dependency functionality changes.

To review dependencies referenced within other DITA content:

  1. Navigate to Assets > Assets Tree.
  2. Select the DITA item, and select the DITA Properties > Used By tab.
    The Used By tab displays DITA assets that reference the currently selected asset.
  3. Choose one of the following filter options.

    Option

    Description

    Direct Usage ReferencesDisplays only direct parent usage references (i.e., distance 1 dependencies) that link to the currently selected item.
    All Usage ReferencesDisplays all ancestor usage references associated with the currently selected asset. This data includes parent dependencies, grandparent dependencies, etc.

    If the currently selected item contains zero usage references, this filter option displays as inactive.

    DITA Properties > Used By Tab

  4. Choose one of the following filter options from the Dependency Version drop-down list:
    Version Notes: CMS 10.6.378
    The Dependency Version drop-down list is exclusive to CMS 10.6.378. If you have CMS 10.6.308–10.6.342, skip this step.

    In CMS 10.6.378, you can filter dependencies based on the latest version or any marked-for-publish version of the DITA asset.

    Option

    Description

    Show All

    Provides a comprehensive list of usage references associated with the DITA asset item, regardless of version or publishing target.

    The Show All option displays all usage reference entries included in the latest version and in any version marked for publish.
    Latest Version

    Indicates which DITA assets include a reference to the current asset item within their latest version of the content.

    For example, if the latest content version of garage-1.ditamap references the current asset, then garage-1.ditamap will display as a usage reference entry in the current asset's Used By tab.

    Note
    • If you make and save changes to the referencing DITA asset item's dependencies, the usage reference entries of the asset being referenced will update to reflect the new changes, no matter if the referencing DITA asset is checked in or out.
    • If no usage references entries display, this indicates the asset is not being referenced by the latest version of any DITA asset.

    Name of Publishing TargetIndicates which DITA assets include a reference to the current asset item within their content version marked to the publishing target you choose from this list.

    For example, if the content version of garage-1.ditamap marked to a publishing target references the current asset, then garage-1.ditamap will display as a usage reference entry for that target in the current asset's Used By tab.

    Note
    If no usage references entries display, this indicates the asset is not being referenced by any DITA asset version marked to that publishing target.

  5. Select or clear the Show Errors Only checkbox.

    If selected, this option displays only usage references that have errors Validity Error Icon in the list. Errors are indicated in the Validity column.

  6. Optional: To search for individual usage references, enter keywords in the Search field based on the Name, Dependency Route, or Type column.
  7. Review the usage references within the list.

    Data includes:

    Data Type

    Description

    Name

    The file name, file extension, and ID of the asset item referenced.

    Tip
    Select the column entry to navigate to the referencing DITA asset.
    DistanceThe hierarchical relationship distance between the current asset item and the referencing DITA item.

    For example, if the distance is 1, then the usage reference entry links directly to current asset item.

    If the distance is 2, then the usage reference entry is a grandparent within the dependency structure. In other words, the usage reference entry links to another DITA item that, in turn, directly references the currently selected asset item (the grandchild dependency).

    Note
    Select the All Usage References filter option to display dependencies with distances greater than 1.
    Dependency Route

    The hierarchical relationship structure of the current DITA item. This route indicates the dependency chain of DITA items that ultimately links to the current item.

    For example, let's say the DITA item garage-1.ditamap is a usage reference entry with the following dependency route:

    garage-1.ditamap/washingthecar.dita/rinsingthecar.dita

    In this example, the file rinsingthecar.dita is the currently selected DITA item. The DITA map garage-1.ditamap references washingthecar.dita, which references rinsingthecar.dita.

    Version Notes: CMS 10.6.308–10.6.342
    To display each entry's dependency route in CMS 10.6.308–10.6.342, select the All Usage References filter option.
    TypeThe type of usage reference. The Type value represents the DITA element (e.g., xref, conref, keydef) in the usage reference that links to the current asset item.
    Confirmed
    Version Notes: CMS 10.6.378 vs. CMS 10.6.308–10.6.342
    The Confirmed column is deprecated in CMS 10.6.378 and is only available in CMS 10.6.308–10.6.342.
    The Dependency Confirmed for Publish check mark indicates the system has registered the dependency within the DITA content and will include the dependency in the next publish.

    The pipeline requires the confirmation of all dependencies before publishing the DITA collection.

    Note
    Users can only publish DITA content at the map level. See Publishing DITA in Ingeniux CMS for details.

    Keep the following in mind:

    • Publishes do not include unconfirmed dependencies. However, if the Show all pages preview option is selected at the time of preview generation, then DITA Preview includes the unconfirmed dependencies.
    • All dependencies of newly created items remain unconfirmed until you check in those new assets.
    • If you or other users add dependencies to checked-out items, the new dependencies remain unconfirmed until checked in.
    • If you or other users remove dependencies from checked-out items, the removed dependencies remain confirmed until checked in.
    Dependency Version
    Version Notes: CMS 10.6.378
    The Dependency Version column is only available in CMS 10.6.378. This column indicates the version of the usage reference that links to the current asset item.

    You can filter the Used By list to only display dependencies for a particular version by using the Dependency Version drop-down list.

    ValidityIf the asset item has conflicts with a usage reference, an error icon Validity Error Icon displays within this column entry. Hover over the icon to view error details.

    See DITA Dependency Validity Errors for details about troubleshooting errors.

    Version Notes: CMS 10.6[378

    CMS 10.6.378 indicates errors for dependencies not marked to publishing targets. You can use the Show Errors Only filter to check for any unmarked dependencies before running DITA publishing pipeline and preview processes.

    If an error icon displays on a usage reference for a particular publishing target, this can indicate the current asset is not marked to that publishing target.

  8. Optional: Select Download CSV to download a .csv file of this data to your local machine.
    Note
    • Download CSV accounts for your filtering selections. For example, if you select Direct Usage References, then only direct dependencies of the DITA asset will be included in your CSV download.
    • The Download CSV button becomes inactive when the Show Errors Only checkbox and Search filter options are applied. Clear these filter options in order to use the download tool.