Key References

You can indirectly link to topics in a map by using key references. You can consider key references as a reuse-friendly alternative to Peer Cross-References.

Overview

Instead of directly linking to a topic by using the exact file path, key references link to a key name assigned to a topic in map. In different maps, topics with key references can link to different topics without limiting topic reuse.

Figure 1. Key Reference Operation.
The following example shows that:
  • “Topic A” and “Topic C” are reused in “Map A” and “Map B”.
  • “Topic C” contains a key reference that links to the “sample_key” key
  • In “Map A”, “Topic C” links to “Topic B” because it has the “sample_key” value assigned
  • In “Map B”, “Topic C” links to “Topic D” because it has the “sample_key” value assigned
Key references

Use Cases

Consider using key references in the following scenarios:

  • When you want to reuse a topic in different maps and want to make the reused topic link to different topics.
    Figure 2. Keyref in the Content Editor.

    The following example shows the linking illustrated in the Key Reference Operation diagram in the Content Editor.


    Key referencing

    Key referencing

Maintenance Guidelines

Keep the following guidelines in mind when using key references:

  • The following Heretto CCMS reports can help you manage key references:
    • Invalid Keyrefs Report checks for broken key references. This report lists keyrefs linking to key names that are not defined in the map.
    • Folder Keys Report identifies all the keys used in a specific folder and where they're used. This report is helpful if you're looking for ways to maximize your reuse opportunities.
  • Develop a key naming convention that is easy to implement and use.
  • Over a given map, we recommend using unique key values.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with key references:

  • Your map won't publish if the key references in the map are not resolved.
  • If there are the same key values in a map, the key resolves to the first instance of that key name in the map.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.