Metadata Governance in Heretto CCMS

1. 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.

2. 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.

3. Deploy API serves the processed content and its remaining metadata to Heretto Portal or a third-party endpoint.

4. 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.

Before you start working with metadata, familiarize yourself with a number of facts and guidelines related to metadata in the Heretto platform.

DITA metadata

• DITA metadata, also referred to as in-document metadata, is DITA elements and attributes stored within the XML structure of DITA files.

• You can view DITA metadata in the XML structure of a DITA map or in the REST URL response directly from the CCMS. See View DITA Content and Metadata for a Resource.

• In topics, the prolog element contains most metadata elements, many of these within the metadata element. For a full list of prolog metadata, see Prolog (metadata) elements (DITA 1.3 Specification).

• In maps, the topicmeta element contains most metadata elements, many of these within the metadata element. For details, see <topicmeta> (DITA 1.3 Specification).

  Note:

  Currently, most DITA metadata added to maps is not passed to deployments or Heretto Portal. Support for map metadata will be available soon.

• In most cases, topic metadata is overridden by map metadata in the topicmeta element. This lets the same topic be used in multiple maps, where different metadata may apply.

• For all DITA metadata configurations, see DITA Metadata Configurations.

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.

• You can view CCMS metadata in the CCMS interface and in the REST URL response for a file. See View CCMS Metadata for a Resource.

• Different system metadata is added to different resources. For example, a folder, a PDF uploaded to the CCMS, and a DITA file created in the CCMS are assigned different system metadata.

• Some system metadata can be customized based on customer preference. For example, Status values.

• Some system metadata can be modified by users with authoring permissions (Author, Editor/Manager, and Administrator). For example, Owner and Status.

• Custom metadata is configured in Heretto CCMS by users assigned the Administrator role. It can be then added to files by users with authoring permissions.

• There are four types of custom metadata: taxonomy, label, text, and date metadata.

• Custom metadata can be added to individual files at file creation or to existing files; it can also be added to a group of files, a map with its dependencies, a folder and its subfolders, or a combination of those in a bulk-change operation. Existing CCMS metadata can be added to, replaced, or removed in a bulk-change operation. This is true for some system metadata and all custom metadata.

• Custom metadata can be configured as search facets (or filters) in the CCMS. To do so, when configuring custom metadata, ensure the Search Facet and Enabled options are selected. Once configured and added to files, custom metadata can be used to filter files from the Search tab. For configuration details, see Custom Metadata Configurations.

• Custom metadata can be configured to apply only to certain content types. For example, you may want custom metadata that applies only to maps. To do this, use the Exclude from Content Type option when configuring metadata in the Metadata interface (Administrators only).

• Custom metadata added to both topics and maps can be carried over to deployments and Heretto Portal HTML. In content processed in a deployment as well as published to portal, map-level custom metadata cascades down to all topics in the map. Map-level custom metadata also cascades down to and is adopted by the sitesection and topichead elements in a map. For details about map-level metadata, see Metadata in maps.

• 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.

• For all custom metadata configurations, see Custom Metadata Configurations.

Extracted Metadata (Beta)

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.

• Extracted metadata can be used only for reporting purposes. Its values are extracted from the content and semantics of your DITA files using custom XPath expressions. Extracted metadata is not included in files, the Heretto Deploy API, or Heretto Portal. Instead, it is stored in a CCMS database and made available in these Insights (Beta) reports: Content Report and Localization Report.

• During the Beta phase, only users assigned the Administrator role can configure extracted metadata and use it in reports. Following full rollout, users assigned the Administrator will retain configuration access, and all users with authoring permissions (Author, Editor/Manager, and Administrator) will be able to use extracted metadata in reports.

• Extracted metadata only extracts details from DITA XML; it can't be used to extract data from non-DITA XML files or CCMS metadata (on-document metadata).

• Extracted metadata uses XPath expressions to extract metadata from DITA files. Once an extracted metadata is configured, the CCMS automatically process all files in all branches and makes results available in reports. Localized and released files are not processed.

• Extracted metadata processing is triggered:

  • Automatically, when content is updated. For example, a topic or map is edited and saved.

  • Automatically, when a new extracted metadata field is configured or an existing field is saved after editing.

  • Manually, when a user assigned the Administrator role triggers reprocessing for an extracted metadata field with the Reprocess all field values button.

• A maximum of 50 extracted metadata fields can be configured in the CCMS. When this limit is reached, the option to add new extracted metadata is disabled. You can remove existing metadata fields to add new ones.

• Each extracted metadata field supports a maximum of five XPath expressions.

• XPath expressions are evaluated in the order they are listed. The first expression that returns a result is used, and subsequent expressions are only evaluated if earlier ones return no match.

• You can specify a default value that is applied to any file with no XPath match. This ensures that files with no XPath match show a meaningful value rather than blank in reports.

• Deleting an extracted metadata field removes it from saved filters and views across all reports.

• For all extracted metadata configurations, see Extracted Metadata Configurations.

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 publishing with Heretto Deploy API

• Heretto Deploy API enables you to publish content from Heretto CCMS to Heretto Portal or a third-party endpoint like a device or machine. When publishing with Deploy API, there are two levels of metadata governance: deployment and Heretto Portal. To learn more, see Metadata Governance in Heretto Portal.

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