Metadata Governance in Heretto Portal

Metadata governance gives your team intentional control over what information accompanies your content at each stage of the delivery pipeline. Rather than accepting default behavior, you can make deliberate choices about exactly which metadata reaches each endpoint.

Metadata governance is the practice of controlling which metadata accompanies your content as it moves from Heretto CCMS through to its delivery endpoints, whether that's Heretto Portal, a third-party system, or a connected device. It gives your team a structured way to decide what information about your content, such as modification dates, taxonomy values, or metadata for audience and product applicability, is included in or excluded from published output.

Important:

Metadata governance support was introduced in Heretto CCMS 25.10.30 and Heretto Portal v6, and requires a two-step activation process. First, the Heretto team must enable the feature in Heretto CCMS. Once that's done, a user assigned the Administrator role in the CCMS must enable and configure metadata in each deployment. Contact your Customer Success Manager to get started.

Metadata governance is most valuable in these areas:

Content exposure control: You decide which metadata belongs in your published output and which should remain internal to the CCMS. This lets you tailor what external audiences see while preserving metadata that supports your internal workflows and content organization.
Search and discoverability: In Heretto Portal, metadata drives search behavior, keyword indexing, and search facets. With governance in place, you can shape the search experience for your end users, ensuring that the appropriate facets are available and that search results surface the most relevant content.
Consistency across delivery endpoints: When your content is served to multiple endpoints such as Heretto Portal or a third-party endpoint like a device or machine, you can tailor metadata for each destination. Governance gives you the flexibility to include different metadata depending on what each endpoint requires.

Heretto provides metadata governance through two levels of control that correspond to stages in the content delivery pipeline:

Deployment-level control, configured in the Deployments interface in Heretto CCMS, determines which custom metadata is included in content published through a deployment. This level of control is available for all delivery endpoints, including Heretto Portal and third-party endpoints, like a machine or device.
Portal-level control, configured in the config.json file associated with your main portal sitemap, provides an additional layer of filtering for content delivered to Heretto Portal specifically. It lets you fine-tune which metadata from a deployment appears in Heretto Portal HTML.

These two levels work together to give you granular control over metadata at each stage of the content delivery process.

Metadata Types in Heretto

Metadata is information about your content, such as author details, modification dates, taxonomy values, or metadata for audience and product filtering. Metadata helps with content management, organization, retrieval, and processing, but typically doesn't appear in the body of your content, such as in paragraphs or notes. Instead, it is stored in the DITA XML structure of your files (in-document metadata) or in visible fields on the document, such as tags or modification dates (on-document metadata). While in-document metadata is specific to DITA files, on-document metadata applies to any file type.

There are two high-level metadata types in your files: DITA metadata and CCMS metadata.

DITA Metadata: DITA metadata, also referred to as in-document metadata, is DITA elements and attributes stored within the XML structure of DITA files.
CCMS Metadata: CCMS metadata, also referred to as on-document metadata, is system and custom metadata added to all files in the CCMS, including DITA and binary files. CCMS metadata is attached to files and stored in the CCMS (as opposed to within the XML structure which is true for DITA metadata). While system metadata is added to files automatically by Heretto CCMS, custom metadata can be configured and added to files by users.
Extracted Metadata (Beta): Extracted metadata is currently used only for reporting purposes, though additional use cases may be supported in future releases. Its values are extracted from the content and semantics of your DITA files using custom XPath expressions. Extracted metadata is not included in files or in Heretto Deploy API or Heretto Portal outputs. Instead, it is stored in a CCMS database and made available in these Insights (Beta) reports: Content Report and Localization Report. Extracted metadata lets you bring information that already exists inside your DITA files into reports for content analysis and insight at scale. For example, you can report on the values of the product attribute or keyword and resourceId elements, as well as any specific wording used in your content.

Note:
This feature is currently in Beta and available to a limited group of customers. General availability for all Heretto customers will follow the conclusion of the Beta phase. Full rollout dates will be shared when available.

Metadata types in Heretto CCMS divided into two groups: DITA metadata that contains metadata elements and attributes, and CCMS metadata that contains system and custom metadata — Figure 1. Types of metadata and related examples.
You can view DITA metadata in the DITA XML structure of a file. See View DITA Content and Metadata for a Resource. You can view system metadata in the Overview tab for a file in Heretto CCMS. See View CCMS Metadata for a Resource. You can view and use extracted metadata (Beta) is these Insights (Beta) reports: Content Report and Localization Report. See Extracted Metadata Configurations.

Metadata Flow in Heretto

When you publish content from Heretto CCMS through a deployment, you can control which metadata reaches your delivery endpoints. Heretto provides two levels of metadata control, deployment and portal, that progressively filter metadata as content moves from the CCMS to its final destination.

Deployment-level metadata control applies only to custom metadata. Portal-level metadata control applies to some custom and system metadata, as well as some portal-specific metadata.

Note:

Extracted metadata (Beta) is used for reporting purposes only and is not included in files, the Heretto Deploy API, or Heretto Portal. For this reason, it is not represented in this metadata flow.

A visual showing the flow of metadata between Heretto CCMS, Heretto Deploy API, Heretto Portal, and a third-party endpoint. It includes numbers that explain what happens when: 1. In a deployment in Heretto CCMS, 2. When Heretto Deploy API processes content, 3. When content is served to Heretto Portal or a third-party endpoint, 4. when additional configurations are added to config.json to further control metadata in Heretto Portal. — Figure 2. Metadata flow and control points in the Heretto platform.

Files stored in Heretto CCMS contain different types of metadata: DITA metadata (elements and attributes), and CCMS metadata (system and custom). When content is published through a deployment, deployment-level metadata control determines which custom metadata is included in the processed content. DITA and system metadata are always included.
Heretto Deploy API processes content and any custom metadata disabled in the deployment. For example, when custom metadata B is not enabled in the deployment, it is removed at this stage and unavailable to any delivery endpoint. For third-party endpoints, this is the only available level of metadata governance.
Deploy API serves the processed content and its remaining metadata to Heretto Portal or a third-party endpoint.
For content served to Heretto Portal, portal-level metadata control provides an additional layer of filtering. For example, in the portal configuration, you can exclude custom metadata A from the portal HTML. It remains available to the portal search engine because that relies on Deploy API.

Deployment-level metadata governance: Users with the Administrator role in Heretto CCMS can configure which custom metadata is included in each deployment through the Deployments interface. Any metadata disabled at this level is removed from the published content entirely, making it unavailable to all delivery endpoints. If a deployment publishes content to a third-party delivery endpoint, this is the only available level of metadata governance.
Portal-level metadata governance: Portal-level metadata provides an additional layer of control over the metadata included in a deployment that enables you to manage some custom and system metadata, as well as some portal-specific metadata. It is configured in the config.json file associated with the main portal sitemap. By default, all metadata included in a deployment is present in portal HTML. Metadata excluded at this level is removed from portal HTML but remains available to the portal search engine. This level of governance is available only when publishing to Heretto Portal.

Metadata Operation and Guidelines

Before you configure metadata in a deployment or Heretto Portal, familiarize yourself with a number of facts and guidelines related to metadata in the Heretto platform.

General

There are two high-level metadata types in your files: DITA metadata and CCMS metadata. DITA metadata, also referred to as in-document metadata, is DITA elements and attributes stored within the XML structure of DITA files. CCMS metadata, also referred to as on-document metadata, is system and custom metadata added to all files in the CCMS, including DITA and binary files, that is stored in the CCMS (as opposed to within the XML structure which is true for DITA metadata).
There are two levels of metadata control: deployment and portal. The deployment-level control is available when publishing to both Heretto Portal and a third-party endpoint; it enables you to control custom metadata. The portal-level control is available only when publishing to Heretto Portal, it enables you to control all custom metadata as well as some system metadata.
System metadata required for Heretto Portal is always carried over to portal HTML. If a config.json configuration (incorrectly) excludes required system metadata, portal ignores the configuration and renders the required metadata. An example of required system metadata is <meta name="robots" content="index, follow">.
Custom metadata is included in a deployment and portal HTML based on its configuration in Heretto CCMS and deployment settings. It must be configured and enabled in the CCMS Metadata interface and added to files. If disabled in the CCMS or in a deployment, it is excluded from the deployment and portal HTML. If enabled in both, it is included.
When configured, custom metadata added to both topics and maps is carried over to deployments and Heretto Portal HTML. Map-level metadata cascades down to all topics in the map. For details on map-level metadata, see Custom metadata in maps below.
Metadata published through active sync and manual deployments behaves the same way.

Metadata and deployments

Deployments let you control custom metadata. System and DITA metadata cannot be configured through the Deployments interface. Only users with the Administrator role in the CCMS can modify and publish deployments.
By default, metadata processing in a deployment is disabled. To enable metadata processing, you must select this check box in the Deployments interface: Select to start processing, without selecting the configuration below is only preparatory. This action is one-way: once saved, it cannot be undone. Once enabled, metadata processing in a deployment can't be disabled.
By default, custom metadata added to maps is excluded from a deployment and therefore can't be passed to Heretto Portal or a third-party endpoint. To enable map-level metadata processing, you must select the Include map-level metadata check box in the Deployments interface (Administrators only). Map-level metadata processing can be disabled in a deployment at any point in time.
By default, no custom metadata is enabled in a deployment. To enable metadata, you must select desired metadata in the Deployments interface.
There are two metadata availability types in a deployment: Optional and Disabled. Optional metadata can be enabled in a deployment. Disabled metadata can't.
If a deployment lists custom metadata as disabled, it means the metadata is disabled in the CCMS Metadata interface (Administrators only).
All metadata included in a deployment is used by the portal search engine, regardless of whether it is filtered from portal through a config.json configuration. This behavior is expected. To exclude metadata from portal search, exclude it on the deployment level.
Changes made in the CCMS Metadata interface are not automatically reflected in deployments. For active sync deployments, you must re-save the deployment. For manual deployments, you must republish. For example, if you disable metadata in the CCMS Metadata interface that is already enabled in a deployment, the deployment continues to reference the old configuration until you re-save or republish it.
When custom metadata enabled in a deployment is disabled in the CCMS Metadata interface, its status in the Deployments interface changes to Disabled (changed). Once the deployment is re-saved, the status becomes Disabled.
When new custom metadata is added to the CCMS Metadata interface, it's listed as optional in the Deployments interface but it's not enabled. Enable it to include it in the deployment.
When custom metadata is removed from the CCMS Metadata interface, it is also removed from the Deployments interface.
If search facets are configured in Heretto Portal but metadata they use is disabled on the deployment level, search facets become unavailable in portal (just as if they weren't configured). For details on portal search facets configuration, see Heretto Portal Search Facets.

Custom metadata in maps

Custom metadata added to maps can be passed to deployments and Heretto Portal or third-party endpoints.
By default, custom metadata added to maps is excluded from a deployment and therefore can't be passed to Heretto Portal or a third-party endpoint. To enable map-level metadata processing, you must select the Include map-level metadata check box in the Deployments interface (Administrators only). Map-level metadata processing can be disabled in a deployment at any point in time.
Two behaviors govern how custom metadata added to maps gets applied to resources and elements in those maps: cascading and adoption.
- Cascading passes metadata downward from the map to everything beneath it, including nested maps, the topics inside them, any sitesection or topichead elements along the way, and any maps and topics added inside those elements. In other words, cascading applies to all resources within a map as well as any sitesection or topichead element it contains.
- Adoption works upward and applies only to sitesection and topichead elements, which take metadata from the maps and topics they reference directly, but not from anything deeper.
- Cascading and adoption apply together, so an element can receive metadata from its ancestors (cascading) and from the maps and topics it references directly (adoption) at the same time. Both behaviors apply in content processed in a deployment as well as published to portal.
- Cascading and adoption apply to content processed by Heretto Deploy API, in both manual and active sync deployments. As a result processed metadata is available in Heretto Portal and third-party endpoints. Neither cascading nor adoption happen in Heretto CCMS or when publishing content with engines like PDF Generator or DITA Open Toolkit (DITA-OT).
Map-level custom metadata cascading rules for resources added to maps:
- All custom metadata types cascade: text, taxonomy, label, and date.
  
  Example: A map has values set for four custom metadata fields: a taxonomy field, a label field, a text field, and a date field. Cascading works like this: all four values are applied to everything beneath the map, including nested maps, topics, and any sitesection or topichead elements.elements and their children.
- Only custom metadata set on maps cascades. Custom metadata set on topics does not cascade.
  
  Example: A map with Audience Level set to Partner contains a topic with Audience Level set to Internal, and that topic has a child topic with no value of its own. Cascading works like this: Partner is applied to both topics, while Internal stays on the topic it is set on and is not applied to the child topic below it.
- For multi-value metadata types (label and taxonomy metadata when configured as multi-value), values from parent and child levels are combined and deduplicated.
  
  Example: A map with Audience Level set to Partner contains a submap with Audience Level set to Internal, which contains a topic with Audience Level set to Partner and Field Engineer. Cascading works like this: Partner, Internal, and Field Engineer are applied to the topic. Partner is supplied by both the map and the topic, but appears only once.
- For single-value metadata types (text and date metadata), the value added to a topic always takes precedence. If a topic has no value set, it inherits from the nearest ancestor map.
  
  Example: A map with Support Tier set to Standard contains two topics, one with Support Tier set to Premium and one with no Support Tier value. Cascading works like this: Premium is applied to the first topic and Standard to the second.
- When a topic is added to multiple maps, each published instance of the topic inherits metadata from its nearest ancestor map in that specific map structure.
  
  Example: A topic with no Support Tier value is added to two maps, one with Support Tier set to Standard and one with Support Tier set to Premium. Cascading works like this: Standard is applied to the instance published from the first map, and Premium to the instance published from the second.
- When chunk="to-content" is set on a topicref element, the chunked output uses only the custom metadata that applies to that topic, including metadata added to that topic and applied through cascading. Custom metadata added to the topics inside the chunked structure is ignored. Custom metadata doesn't cascade to child topics in the chunked structure.
  
  Example: A map with Audience Level set to Partner contains a topic with chunk="to-content" applied and Audience Level set to Internal, and that topic has three child topics, each with its own Audience Level value. Chunking works like this: Partner and Internal are applied to the chunked structure, and the values added to the three child topics are ignored.
Map-level custom metadata cascading and adoption rules for sitesection and topichead:
- Cascading passes metadata down to a sitesection or topichead element from its ancestor maps. Metadata from those ancestors continues to cascade to maps and the topics nested inside them, at every level.
  
  Example: A map with custom metadata Audience Level set to Partner contains a sitesection with a nested submap that contains three topics, each with a number of child topics. Cascading works like this: Partner is applied to the sitesection, the nested submap, all three topics, and every one of their child topics.
- Adoption pulls metadata up to a sitesection or topichead element from the maps and topics it references directly, but not from anything deeper. A value set on a grandchild map is not adopted.
  
  Example: A map with no custom metadata contains a sitesection with a nested submap that has Audience Level set to Internal and contains three topics, one of which has a child topic with Audience Level set to Field Engineer. Adoption works like this: Internal is applied to the sitesection, because the submap is referenced directly by it, while Field Engineer is not, because the child topic carrying it sits two levels below. Field Engineer stays on that child topic alone.
- An adopted value applies to the sitesection or topichead element only. It is not passed on to the other maps and topics that element references, which keep their own values plus anything cascaded from above.
  
  Example: A sitesection references two submaps, the first with Audience Level set to Internal and the second with no Audience Level value. Internal is applied to the sitesection, but the second submap has no value.
- For multi-valued metadata (label or taxonomy metadata configured as multi-value), the sitesection or topichead element aggregates the distinct values of all the maps and topics it references directly, together with any value cascaded from its ancestors.
  
  Example: A map with Audience Level set to Partner contains a sitesection that references two submaps, one with Audience Level set to Internal and one with Audience Level set to Field Engineer. Aggregation works like this: Partner, Internal, and Field Engineer are applied to the sitesection. A value supplied by more than one source appears only once.
- For multi-valued metadata (label or taxonomy metadata configured as multi-value), a referenced map or topic with no value for a metadata field contributes nothing to the aggregated value.
  
  Example: A map with Audience Level set to Partner contains a sitesection that references two submaps, one with Audience Level set to Internal and one with no Audience Level value. Partner and Internal are applied to the sitesection.
- For single-valued metadata (text and date metadata), the value that originates furthest from the root map takes precedence. An adopted value comes from a map or topic below the element, so it originates further from the root than a value cascaded from an ancestor map above it and overrides the cascaded value.
  
  Example: A map with Support Tier set to Standard contains a sitesection that references a submap with Support Tier set to Premium. Precedence works like this: Premium is applied to the sitesection, and the cascaded Standard is rejected.
- For single-valued metadata, when a sitesection or topichead element references two or more maps or topics, it adopts the value of the first one it references and ignores the values of the rest.
  
  Example: A sitesection references three submaps, with Support Tier set to Premium, Basic, and Enterprise respectively. Premium is applied to the sitesection. Reordering the references changes which value is applied.
- If the first map or topic referenced by a sitesection or topichead element has no value for a single-valued metadata field, the element adopts nothing and keeps the value cascaded from its ancestors. It does not fall through to the next referenced map or topic.
  
  Example: A map with Support Tier set to Standard contains a sitesection that references two submaps, the first with no Support Tier value and the second with Support Tier set to Basic. Standard is applied to the sitesection.
- When chunk="to-content" is applied to a sitesection or topichead element, the chunked output uses only the custom metadata that cascading and adoption applied to that element. Custom metadata set on the content inside the chunked structure is not included.
  
  Example: A map with Audience Level set to Partner contains a sitesection with chunk="to-content" applied, which references three submaps, each with its own Audience Level value. Chunking works like this: Partner is applied to the chunked structure, and the values set on the three submaps are not included.

Metadata and Heretto Portal

You can control some system metadata and all custom metadata present in Heretto Portal HTML by adding configurations to the config.json file associated with your main portal sitemap. See Filter Metadata in Heretto Portal.
When no metadata configuration is present in config.json (the default), all metadata included in a deployment is carried over to portal HTML.
Metadata included in portal HTML is added to HTML meta elements within the head section of a portal page. To view portal HTML, inspect a portal page in a browser.
If a config.json configuration (incorrectly) excludes required system metadata, portal ignores the configuration and renders the required metadata. An example of required system metadata is <meta name="robots" content="index, follow">.
By default, portal HTML includes the generator meta tag <meta name="generator" content="HerettoPortal"> that identifies Heretto Portal as the software that created your help site. You can exclude or overwrite it with a value of your choice. See Configure the generator Meta Tag for Heretto Portal.
By default, Heretto Portal HTML includes social platform metadata that informs the platform, like LinkedIn or Facebook, what to include in the preview. You can configure this metadata to include only selected or exclude all platforms. See Configure Social Platform Metadata for Heretto Portal.
You can add static metadata that is not present in files in the CCMS to all content in your portal through a config.json configuration. See Configure Static Metadata for Heretto Portal.

Custom metadata and Heretto Portal

Custom metadata is CCMS metadata that can be configured and added to files in Heretto CCMS. It includes: taxonomy, label, text, and date metadata. In some situations, taxonomy metadata behaves differently from label, text, and date metadata.
Custom metadata is included in a deployment and portal HTML based on its configuration in Heretto CCMS and deployment settings. It must be configured and enabled in the CCMS Metadata interface and added to files. If disabled in the CCMS or in a deployment, it is excluded from the deployment and portal HTML. If enabled in both, it is included.
In portal HTML, each custom metadata is added in its own meta element. For example, here is a label metadata value Technician added within a User Role metadata category:
CODE
<meta name="User_Role" content="Technician">
```
<meta name="User_Role" content="Technician">
```
Similarly, a taxonomy metadata value Beginner added within a User Type metadata category:
CODE
<meta name="User_Type" content="Beginner">
```
<meta name="User_Type" content="Beginner">
```
However, taxonomy metadata is also added to the <meta name="keywords"> HTML element. For example:
CODE
<meta name="keywords" content="Beginner">
```
<meta name="keywords" content="Beginner">
```
Taxonomy metadata can be configured as search facets in Heretto Portal. Search facets must be configured in Heretto CCMS, added to files, and enabled on the deployment level. If search facets are configured in Heretto Portal but metadata they use is disabled on the deployment level, search facets become unavailable in portal (just as if they weren't configured). For details on how to configure portal search facets, see Heretto Portal Search Facets.
Taxonomy metadata can be configured in Heretto CCMS as drop-downs for DITA attributes like audience and product (conditional processing attributes), or outputclass. This configuration is also known as taxonomy-driven attributes. For details, see Configure Drop-downs for DITA Attributes.
Date metadata is presented in the Unix time format. For example,
CODE
<meta name="Valid_Thru" content="1770076800000">
```
<meta name="Valid_Thru" content="1770076800000">
```

Metadata and Heretto Portal search

The portal search engine uses metadata included in the <meta name="keywords"> HTML element. This element combines metadata from different sources: keywords added in the topic prolog element, taxonomy metadata added to files, and portal breadcrumbs. Which of this metadata is added to portal HTML varies. For details, see keywords in Metadata Values Available for Filtering Reference.

Note:
In Heretto Portal v6, keywords is a CCMS metadata field that shows only keywords added within the prolog element of a DITA topic.

Staring on April 16, portal v6 becomes the default experience for new Heretto customers. Existing portal customers will be migrated to v6 through a tailored approach, guided by a discovery-driven process aligned to their specific needs and technical requirements. Reach out to your Customer Success Manager (CSM) to learn more about what this process will look like for your team.
By default, taxonomy metadata is visible as tags at the bottom of a portal page and in search results. When taxonomy metadata is included in a deployment but excluded through a portal config.json configuration, the metadata is no longer visible as tags on portal pages but is still available to portal search. To exclude taxonomy metadata from portal search, exclude it on the deployment level.

Figure 3. Metadata tags at the bottom of a portal page.
Taxonomy metadata can be configured as search facets in Heretto Portal. Search facets must be configured in Heretto CCMS, added to files, and enabled on the deployment level. If search facets are configured in Heretto Portal but metadata they use is disabled on the deployment level, search facets become unavailable in portal (just as if they weren't configured). For details on how to configure portal search facets, see Heretto Portal Search Facets.

Metadata and chunked content

When chunk="to-content" is applied to an element that has child topics, metadata in Heretto Portal behaves like this:

System metadata from the parent topic, like lastModified, is used, while system metadata from child topics is ignored. This means that the Last updated date shown on a chunked portal page shows the modification date of the parent topic.
Custom taxonomy, label, text, and date metadata from the parent topic is used, and custom metadata from child topics is ignored.
Keywords from the DITA prolog element of both parent and child topics are merged and used.
All metadata is shown at the bottom of the chunked page.

Known limitations

Currently, the only system metadata supported in Heretto Portal is:
- lastModified
- lastModifiedISO
- contentType
DITA metadata that is not passed to deployments or Heretto Portal:
- prodinfo
- linktext
- topicmeta - passed to deployments but not to Heretto Portal
- othermeta
- copyright
Changes made in the CCMS Metadata interface are not automatically reflected in deployments. For active sync deployments, you must re-save the deployment. For manual deployments, you must republish. For example, if you disable metadata in the CCMS Metadata interface that is already enabled in a deployment, the deployment continues to reference the old configuration until you re-save or republish it.