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.


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.

Assign Key Names

You must set a key name on a topicref element in a map to indirectly link to a topic.

  1. In the content library, hover over a map and click the Dock button.
  2. In the Map Editor, hover over the topic you want to assign a key name to.
    A quick list of icons shows.
  3. Click the Key icon.
  4. In the Keys field, enter a key name and click Update.
Insert a key reference. See Insert Key References.

Insert Key References

Create an indirect, inline link by inserting a key reference to a key name.

In a map, assign a key name to the topicref element that you want to indirectly link to. See Assign Key Names.
  1. In the content library, hover over a topic and click Open.
  2. In the toolbar, click the Insert Link icon.
  3. In the Link dialog, from the Link To drop-down menu, select Key (key reference).
  4. Under the Keyref field, in the list, double-click a key.
    Remember: You must open a map or set map context to see available keys and resolve key references.