Extracted Metadata Configurations

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 (Beta) 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.

The Create Extracted Field window with a sample configuration that extracts values from the keyword element; for files with no keywords added, the default value of "no-keyword-set" will be returned in reports — Figure 1. An Example Extracted Metadata Configuration.
An extracted metadata field configured to extract values added inside the `keyword` element. For files with no keywords added, reports will show the default value of `no-keyword-set`. On the right, a preview of the results enables you to verify the configuration.

Figure 2. An Example of Extracted Metadata Visualized in a Chart in the Content Report.

A visual representation of extracted metadata configured in the Content Report (Insights (Beta)). This example shows how keywords extracted from DITA files are presented in a bar chart.

A listing of files in the Content Report with a number of default columns like Filename, Content Type, Status, Owner, and Last Modified, and a custom column Keywords that shows the values added within the DITA keyword element — Figure 3. An Example of Extracted Metadata Listed in a Column in the Content Report.
A file listing in the Content Report showing default columns, like Filename, Content Type, and Status, and a custom Keyword column. The Keyword column shows the values added in the DITA `keyword` element for each file listed. For files with no keywords added, the report shows the default value of `no-keyword-set`.

Create an Extracted Metadata Field

Create an extracted metadata (Beta) field to extract data from DITA files and make it available for content analysis and insight in these Insights (Beta) reports: Content Report and Localization Report.

When you add an extracted metadata field, you define the XPath logic that Heretto CCMS uses to derive values from your files. You can add up to five XPath expressions per field. Expressions are evaluated top-down, the first expression that returns a result is used, and subsequent expressions are only applied when earlier ones return no match. You can configure up to 50 extracted metadata fields in the CCMS.

To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.

In the top-left corner, click Main Menu and go to Metadata.
Select the Extracted Metadata tab.
Click Add Field.

Note:
If the Add Field button is disabled, you have reached the maximum limit of 50 extracted metadata fields. Delete an existing field before adding a new one.
In the Display Name field, enter a descriptive name for the metadata field.

Display name shows in the extracted metadata listing and any reports that use this metadata.
Optional: Modify the Field Name field.

Field name is used by the CCMS as a unique system identifier and is populated automatically. At this point, you can still modify it. Once you save your changes, this field becomes uneditable. Use a name that clearly identifies this field for system and integration purposes.
From the Data Type options, select the type of value this field will produce.

Options are: Text, Number, Boolean, and Date/Time. At save time, the CCMS validates that the values returned by your XPath expression(s) match the selected data type. If a mismatch is detected, an error is returned and the configuration is not saved.
Optional: In the Default Value field, enter the value to apply to files for which none of the XPath expressions return a match.

Setting a default value ensures that files with no XPath match show a meaningful value rather than blank in the Content Report and Localization Report, including in CSV exports. Common examples include uncategorized or no-keyword-set for the keyword element or 0 for a link count.
In the XPath Expressions field, enter your first XPath expression.

The expression is validated at save time. If the expression is not valid XPath, an error is returned.
Optional: To add additional XPath expressions, click Add XPath and enter another expression.

You can add up to five XPath expressions per extracted metadata field. When five expressions have been entered, the Add XPath button is disabled. Hover over the disabled Add XPath button to see a tooltip confirming the limit has been reached.

Expressions are evaluated in the order they are listed. To remove an expression you no longer need, click Remove XPath next to it. Deleting an expression is only available when more than one expression is present.
In the XPath Preview section on the right, select a folder to preview the results and verify your configuration.

The preview shows up to 50 files that match your criteria.

Figure 4. An example of an extracted metadata configuration for the keyword element.
For files with no keywords added, reports will show the default value of no-keyword-set.
Click Create.

Heretto CCMS validates the XPath expressions and data type compatibility. If validation passes, the new extracted metadata field is added to the listing and processing begins automatically.

Figure 5. Extracted metadata listing that shows the new keyword field and a 2% processing progress

The extracted metadata field is saved and listed in the Extracted Metadata interface. Heretto CCMS automatically begins computing metadata values for all files in scope. A progress indicator on the listing row shows the computation status.

The new metadata field is now available in these Insights (Beta) reports: Content Report and Localization Report.

Use Extracted Metadata in Reports

Once configured and processed, extracted metadata (Beta) automatically becomes available in these Insights (Beta) reports: Content Report and Localization Report. Reports enable you to visualize extracted metadata in a chart (Content Report only), filter report results, and show it in a column in the report file listing. You can use extracted metadata for a map or folder.

Note:

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

To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.

Configure extracted metadata in Heretto CCMS. See Create an Extracted Metadata Field.

In the Content Library, click a map or folder for which you want to view extracted metadata.
In the Resource Drawer that opens on the right, click Insights.
The Content Report opens.

Visualize extracted metadata in a chart (Content Report only)

In the Content Report, scroll down past the charts available by default and click Add Chart.
Configuring custom charts is possible only in the Content Report. One report can contain up to 16 charts.
In the Configure Chart window, choose desired data fields, visualization type, and layout for this chart.
You can use extracted metadata in two fields Group By, a required field available for both pie and bar charts that determines the category for each bar or slice in the chart, and Stack By, an optional field available only for bar charts that stacks data within a category.
Tip:
Explore different chart types and settings to find the best fit for your data. Charts are easy to edit, and you can add multiple charts side by side to compare visualizations before deciding which works best for your use case.
Figure 6. An example of two bar charts configured to show the same data differently.
This example shows how you can create different charts for the same data for comparison and then decide which one works best. The Keywords (Group By) chart uses extracted metadata Keyword in the Group By field and Content Type in the Stack By field. The Keywords (Stack By) chart uses extracted metadata Keyword in the Stack By field and Content Type in the Group By field.
Click Add Chart to save your settings.
If the Add Chart button is inactive, a required setting is missing in your configuration. Specify it to add the chart.
Optional: Drag and drop the chart to a desired position in the report by using Drag and drop chart.
Optional: Save the report to preserve the new chart and gain the ability to access it at any point in time by clicking Save as new View.
Once you save your first report, you can switch between saved report views by using the View drop-down menu.
Note:
Until both extracted metadata (Beta) and Insights (Beta) are fully released only users assigned the Administrator role can access Insights reports.
Figure 7. The View and Save as new View options in the Content Report

Filter report results with extracted metadata

In a report, click Add and from the Metadata list select the desired extracted metadata.
Figure 8. The Add option that enables you to add custom filters
Define a value for the filter.
Depending on the extracted metadata type you selected, you'll need to provide a number, enter a value or select it from a list, or specify a date or date range.
Optional: Save your changes by clicking Save as new View or, if you edited a previously saved view, by clicking Save Changes.
Once you save your first report, you can switch between saved report views by using the View drop-down menu.
Figure 9. The save options in a Content Report view that uses metadata extracted from the keyword element as a filter

Show extracted metadata in a column in the report file listing

In a report, scroll down to the file listing, click Add Column and from the Extracted list select the desired extracted metadata.
Figure 10. The Add Column button in the Content Report
Optional: Sort values in the column.
Optional: Save your changes by clicking Save as new View or, if you edited a previously saved view, by clicking Save Changes.
Once you save your first report, you can switch between saved report views by using the View drop-down menu.
Figure 11. The Save as new View button in the default Content Report view that shows metadata extracted from the keyword element in the file listing

Edit an Extracted Metadata Field

You can edit any property of an extracted metadata (Beta) configuration except the Field Name, which is a unique system identifier that becomes uneditable after the configuration is first saved. Editing a configuration, for example, changing an XPath expression, automatically triggers reprocessing of metadata values for all DITA files in all branches.

Important:

Changes to extracted metadata configurations may affect existing reports. Review any reports or report views that reference this field before making significant changes.

To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.

Configure extracted metadata in Heretto CCMS. See Create an Extracted Metadata Field.

In the top-left corner, click Main Menu and go to Metadata.
Select the Extracted Metadata tab.
In the listing, locate the extracted metadata field you want to modify and click Edit Field.
Make your changes to the editable fields: Display Name, Data Type, Multi-value, Default Value, and XPath Expressions.
When editing an extracted metadata field, keep this information in mind:
- The Field Name is read-only and cannot be modified after the configuration is first saved.
- You can add up to five XPath expressions per extracted metadata field. When five expressions have been entered, the Add XPath button is disabled.
- Removing an XPath expression is only available when more than one expression exists.
In the XPath Preview section on the right, select a folder to preview the results and verify your configuration.

The preview shows up to 50 files that match your criteria.
Figure 12. An example of an extracted metadata configuration for the keyword element.
For files with no keywords added, reports will show the default value of no-keyword-set.
Click Update.

The CCMS validates the XPath expressions and data type compatibility. If validation passes, the updated configuration is saved and reprocessing begins automatically.
Figure 13. Extracted metadata listing that shows the updated keyword field and a 2% processing progress

The updated extracted metadata configuration is saved. The CCMS automatically reprocesses metadata values for all DITA files in all branches. A progress indicator on the listing row shows the reprocessing status.

Delete an Extracted Metadata Field

Remove an extracted metadata (Beta) field that is no longer needed. Deletion permanently removes the configuration and its associated values from reports.

Warning:

Deleting an extracted metadata field is permanent and cannot be undone. The deleted field and its values are removed from all reports. Before proceeding, review any reports or report views that use this field.

To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.

Configure extracted metadata in Heretto CCMS. See Create an Extracted Metadata Field.

In the top-left corner, click Main Menu and go to Metadata.
Select the Extracted Metadata tab.
In the listing, locate the extracted metadata field you want to remove and click Delete Field.
In the confirmation dialog that opens, click Delete to confirm.

The extracted metadata field is permanently removed from the listing. Its values are removed from all reports. This action cannot be undone.

Reprocess Extracted Metadata and Monitor Progress

Manually trigger reprocessing of extracted metadata (Beta) values for an extracted metadata field, and monitor the progress of any active computation directly from the listing.

Heretto CCMS automatically triggers reprocessing of extracted metadata values whenever content is updated or an extracted metadata configuration is created or edited. You can also manually trigger reprocessing at any time from the extracted metadata listing. This option is useful, for example, after making bulk changes to your content or to verify that values are up to date.

To complete this procedure, you must be assigned the Administrator role in Heretto CCMS.

Configure extracted metadata in Heretto CCMS. See Create an Extracted Metadata Field.

In the top-left corner, click Main Menu and go to Metadata.
Select the Extracted Metadata tab.
In the listing, locate the extracted metadata field you want to reprocess and click Reprocess all field values.
The CCMS begins evaluating your XPath expressions against all DITA files in all branches. Localized and released files are not included in this operation. A progress bar shows the current completion percentage.

Figure 14. Extracted metadata listing that shows a 2% reprocessing progress

When the progress indicator reaches 100%, reprocessing is complete, and all extracted metadata values for the field are up to date.

Under maintenance

Heretto Help

Extracted Metadata Configurations

Create an Extracted Metadata Field

Use Extracted Metadata in Reports

Edit an Extracted Metadata Field

Delete an Extracted Metadata Field

Reprocess Extracted Metadata and Monitor Progress

Footer Section

Our Support Team is here to help