Show Page Sections

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.

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, right-click a map and select Dock button.
  2. In the Map Editor, hover over the topic you want to assign a key name to.
  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, right-click a map and select Dock button.
  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.