Heretto Portal Search Facets

1. In the top-left corner, click the Main Menu and go to Taxonomy.
2. Click New Taxonomy.
3. Enter a label for the taxonomy.

   The Label field is the name of the taxonomy that is not visible to users outside of this interface. The Name field is used by the CCMS as a unique identifier and is populated automatically. At this point, you can still modify the value in the Name field. Once you save your changes, you can still modify the label but not the name.

4. Click Save to create the new taxonomy.
5. Click the taxonomy to add taxonomy terms.
6. Click the existing term Unnamed 1 and, in the Label field, give it a meaningful name.

   Once configured, the name you give a taxonomy term in the Label field is visible to other users. The Name field is not editable for existing taxonomy terms.

7. Click Save.
8. Right-click the renamed term and do any of the following:

   • To create a new, top-level term, select Create Term Below.

   • To create a child term under the existing term, select Create Narrower Term.

9. Give the new term a meaningful name. Click Save.
10. Keep adding new terms as needed.
11. Once you are satisfied, click Save all changes.

You added a taxonomy in the CCMS and populated it with terms. It is not visible anywhere outside of the Taxonomy interface. You are ready to enable the taxonomy as metadata.

Enable Search Facet Taxonomy as Metadata

1. In the top-left corner, click the Main Menu and go to Metadata.
2. If needed, scroll down to the Category Name field, enter a name for the metadata category, and click Add Category.

   The value you add to the category is visible to other users in the Overview tab of the Resource Drawer.

3. Optional: To prevent this metadata from being added to selected content types, for example, task, map, or DITAVAL, in the Exclude from Content Type field, choose those content types.

   By default, metadata can be added to all content types.

4. Optional: To prevent this metadata from being added to binary files, such as image or CSS files, clear the Enable for binary files check box.
5. Complete these fields:
   1. In the Label field, enter a metadata field label.

      The value you add in the Label field is visible to other users in the CCMS. The Name field is used as a unique identifier by the CCMS and is populated automatically. At this point, you can still modify the name. Once you save your changes, you can still modify the label but not the name.

   2. In the Type drop-down menu, select Taxonomy.
   3. In the Values field, select a taxonomy structure.

      These are the taxonomy values you want to associate with your metadata category.

6. Optional: To enable users to select multiple values, select Allow Multiple Selection.
7. Optional: To enable users to use the metadata as search filters in the CCMS, select Search Facet.
8. Select Enabled to enable the metadata for use in the CCMS.

   If you keep this option cleared, your metadata settings will be saved in but the metadata won't be available for users to add to files or use as search facets (if you selected Search Facet).

9. Optional: Add more metadata fields in this category by clicking Add Field and repeating the process.

   One metadata category can contain multiple metadata fields of the same or different types. For example, one category can contain taxonomy and date metadata fields.

   Tip:

   If you added two or more metadata fields to a metadata category, you can order them by using the Move Up and Move Down options from the hamburger menu .

10. Click Add Field, then Save Changes.
    Note:

    Due to a known issue, for all changes to save, the category must contain an empty metadata field at the bottom.

Your metadata category should look similar to this. Note the empty third field (expected).

Add Search Facet Metadata to Files

You add search facet metadata to files on the master branch. Once configured, that metadata becomes search facets in the environment that is associated with the master branch. To see search facets in other portal environments, including production, you need to push all your changes from master to branches associated with those portal environments.

1. In the Content Library, ensure that you are working in the master branch.

2. In the Content Library, click a file to open the Resource Drawer.
3. In the Resource Drawer, scroll down and add metadata from the available options.
4. Repeat these steps for any other file you want to add metadata to.

5. In the Content Library, select the files, folders, or maps you want to modify.

   To select a range of files and folders, select the first file or folder, press and hold Shift, and select the last file or folder in the range.

6. Right-click the selection and select Bulk Change > Metadata.
7. If your selection includes a folder, decide if you want files in its child folders (folders it contains) to be included in this operation.
8. If your selection includes a map, decide which files associated with it you want to be included in this operation:
   1. If you don't want to include the dependencies of a given map, like its child topics and submaps, clear the Include dependencies check box.
      Important:

      The Include dependencies option only includes the direct dependencies of the map. It does not include binary files (non-text files like images) present in the map or topics it contains.

   2. If you don't want to change the resource-only files in a map, clear the Include resource-only files check box.
      Tip:

      For example, the resource-only files are your variable topics that are added with the processing-role="resource-only" attribute to your map. As a result, they are present in the map but not included in the output.

   3. If you want to include all map dependencies, including its indirect dependencies and binary files (non-text files like images), select the Include all dependencies check box.
9. Select the metadata you want to modify and an action you want to perform:

   Option	Description
   Add to existing	Metadata values are added to the selected files. Existing metadata values, if any, remain unchanged.
   Clear field	All metadata values in the selected files are removed.
   Replace all with	All metadata values in the selected files are removed and replaced with the new metadata.
   Find and remove these	Specified metadata values are removed from the selected files.

10. Select the metadata value(s) to apply the selected action to.
11. Click Save.

Your files now have metadata assigned to them. You can view the metadata for a file by clicking the file and scrolling down in the Overview tab of the Resource Drawer. From there, you can also expand the API Info view and click REST URL to view all metadata for a file.

You are now ready to enable the metadata as Heretto Portal search facets. If you localize your content, this is also a good moment to send your search facets for localization.

Send Portal Search Facets for Localization

1. Gather all your search facets in the source language in a document that your Localization Services Provider (LSP) accepts.

   For example, your LSP might want to work with a .docx, .xlsx, .txt or a specialized document type.

   You only need to localize the values in the Label field that both the Taxonomy and Metadata interfaces use for your search facets. Ideally, that document reflects the parent-child hierarchy of your search facets present in Heretto CCMS, which might help translators with context.

   1. In the CCMS, go to the Main Menu in the top-left corner and select Metadata.
   2. Scroll down to a metadata category with your search facet configuration.
   3. Copy the relevant value in the Label column and add it to the document you will be sending to your LSP.

   4. Click the field for the corresponding Values column and add the selected value along with its children to the document you will be sending to your LSP.

2. Repeat these steps for any other search facets that need to be localized.
3. Once you add all search facets to the document, send it to your LSP.

Once you get the localized search facets back from your LSP, you can add them to your portal configuration.

Add Localized Portal Search Facets to Portal Configuration

1. In the Content Library, ensure that you are working in the master branch and go to your main portal sitemap.
2. Open the main portal sitemap.
3. In the map tree pane, click the Gear button and set your options like this:
   1. Set Icons to On.
   2. Set Show Elements to All.
   3. Set Element Names to Full.

   The map tree now shows color-coded elements with full element names. This view enables you to easily identify and modify all elements in your sitemap.

4. Expand the sitemeta element, right-click the config.json element, and select Show file in Content Library.

5. In the Content Library, right-click the config.json file and select Edit Source.
6. In the Source Editor, press Ctrl/Cmd > F and search for i18n (internationalization).

   The i18n parameter you are looking for contains the en language code with default portal labels in English.

   JSONCopy

   "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" } },

   "i18n": {
           "en": {
   	    "label.tenant": "[REPLACE]",
               "label.section": "Subject",
               "label.home": "Home",
               "label.sections": "Sections"
           }
       },

7. Scroll to the end of the en object and paste this code right after the closing bracket of the en object:
   JSONCopy

   "locale_code": { "metadata_name_value": "localized_label_value", "metadata_name_value_2": "localized_label_value" } }

   "locale_code": {
   		"metadata_name_value": "localized_label_value",
   		"metadata_name_value_2": "localized_label_value"
   	}
   }

   where:

   • locale_code is the code of the target language you translated your content and search facets to. For example, de and de-de are two different codes. The locale code that you configure for search facets needs to match the codes used in your main sitemap and localized content.

   • metadata_name_value is the value present in the Name column of the Metadata interface

   • localized_label_value is the localized search facet that corresponds to the metadata_name_value

   At this point, your i18n parameter should look like this:

   JSONCopy

   "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "locale_code": { "metadata_name_value": "localized_label_value", "metadata_name_value_2": "localized_label_value" } },

   "i18n": {
           "en": {
   	    "label.tenant": "[REPLACE]",
               "label.section": "Subject",
               "label.home": "Home",
               "label.sections": "Sections"
           },
   
   	"locale_code": {
   	    "metadata_name_value": "localized_label_value",
   	    "metadata_name_value_2": "localized_label_value"
   	}
       },

   Note:

   The Source Editor automatically validates the .json file. Errors are indicated by a red wavy line. When you hover over it, you get error details. The most common errors in .json files are missing or extra commas at the end of lines. The last line added inside curly braces ({}) should have no comma at the end.

8. In the config.json file, replace locale_code with the locale code your search facets are translated to.

   The locale code needs to correspond to the locale code you use to localize your content in the CCMS and should be added inside quotation marks (""): "de-de".

   At this point, your i18n parameter should look like this:

   JSONCopy

   "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "de-de": { "metadata_name_value": "localized_label_value", "metadata_name_value_2": "localized_label_value" } },

   "i18n": {
           "en": {
   	    "label.tenant": "[REPLACE]",
               "label.section": "Subject",
               "label.home": "Home",
               "label.sections": "Sections"
           },
   	"de-de": {
   	    "metadata_name_value": "localized_label_value",
   	    "metadata_name_value_2": "localized_label_value"
   	}
       },

9. Open the CCMS in a new tab or window, and from the Main Menu in the top-left corner select Metadata.
10. Scroll to a localized metadata and copy the value in the Name column.

11. Go back to the config.json file, and paste the copied value in place of metadata_name_value.

    The pasted value should be added inside quotation marks (""): "Category".

    At this point, your i18n parameter should look like this:

    JSONCopy

    "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "de-de": { "Category": "localized_label_value", "metadata_name_value_2": "localized_label_value" } },

    "i18n": {
            "en": {
    	    "label.tenant": "[REPLACE]",
                "label.section": "Subject",
                "label.home": "Home",
                "label.sections": "Sections"
            },
    	"de-de": {
    	    "Category": "localized_label_value",
    	    "metadata_name_value_2": "localized_label_value"
    	}
        },

12. In the config.json file, replace localized_label_value with a translation of the label associated with the metadata name value.

    At this point, your i18n parameter should look like this:

    JSONCopy

    "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "de-de": { "Category": "Kategorie", "metadata_name_value_2": "localized_label_value" } },

    "i18n": {
            "en": {
    	    "label.tenant": "[REPLACE]",
                "label.section": "Subject",
                "label.home": "Home",
                "label.sections": "Sections"
            },
    	"de-de": {
    	    "Category": "Kategorie",
    	    "metadata_name_value_2": "localized_label_value"
    	}
        },

13. Repeat 9 through 12 for any metadata for this locale (target language). Add more locales as needed. Click Save.

14. In the config.json file, go to the locale (target language) for which you want to add search facet localizations and add this string to it: "facet.taxonomy_name_value": "localized_label_value".
    JSONCopy

    "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "de-de": { "Category": "Kategorie", "metadata_name_value_2": "localized_label_value", "facet.taxonomy_name_value": "localized_label_value" } },

    "i18n": {
            "en": {
    	    "label.tenant": "[REPLACE]",
                "label.section": "Subject",
                "label.home": "Home",
                "label.sections": "Sections"
            },
    
    	"de-de": {
    	    "Category": "Kategorie",
    	    "metadata_name_value_2": "localized_label_value",
    	    "facet.taxonomy_name_value": "localized_label_value"
    	}
        },

15. Open the CCMS in a new tab or window, and from the Main Menu in the top-left corner select Taxonomy.
16. Go to a taxonomy and select the taxonomy term that you want to localize.
17. Copy the value in the Name field.

18. In the config.json file, replace taxonomy_name_value with the copied value.

    In our example, replace taxonomy_name_value with user_guide.

    At this point, your i18n parameter should look like this:

    JSONCopy

    "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "de-de": { "Category": "Kategorie", "metadata_name_value_2": "localized_label_value", "facet.user_guide": "localized_label_value" } },

    "i18n": {
            "en": {
    	    "label.tenant": "[REPLACE]",
                "label.section": "Subject",
                "label.home": "Home",
                "label.sections": "Sections"
            },
    
    	"de-de": {
    	    "Category": "Kategorie",
    	    "metadata_name_value_2": "localized_label_value",
    	    "facet.user_guide": "localized_label_value"
    	 }
        },

19. In the config.json file, replace localized_label_value with the translation of the taxonomy term.

    In our example, replace localized_label_value with Benutzerhandbuch.

    At this point, your i18n parameter should look like this:

    JSONCopy

    "i18n": { "en": { "label.tenant": "[REPLACE]", "label.section": "Subject", "label.home": "Home", "label.sections": "Sections" }, "de-de": { "Category": "Kategorie", "facet.user_guide": "Benutzerhandbuch" } },

    "i18n": {
            "en": {
    	    "label.tenant": "[REPLACE]",
                "label.section": "Subject",
                "label.home": "Home",
                "label.sections": "Sections"
            },
    
    	"de-de": {
    	    "Category": "Kategorie",
    	    "facet.user_guide": "Benutzerhandbuch"
    	}
        },

20. Repeat these actions for any other taxonomy terms. Click Save.

Enable Search Facet Metadata in Deployments

1. In the top-left corner, click the Main Menu and go to Deployments.
2. Click the deployment you want to edit and click Edit Deployment.
3. In the Metadata Governance section, select this check box: Select to start processing, without selecting the configuration below is only preparatory. This action is one-way: once saved, it cannot be undone.

   By default, metadata processing is disabled in all deployments. Selecting this check box enables it for the current deployment. Once enabled, you cannot disable metadata processing or repeat this step.

   Note:

   If you don't see the Metadata Governance section, it means the metadata governance feature hasn't been enabled in the CCMS yet.

4. In the Metadata Governance section, review the list of custom metadata and select check boxes next to the metadata you want to enable.

   If a deployment lists custom metadata as disabled, it means the metadata is disabled in the CCMS Metadata interface (Administrators only).

5. Click Save.

The enabled metadata is included in active sync deployments upon saving. Manual deployments must be published. Once processed, the enabled metadata will be served to Heretto Portal or a third-party delivery endpoint, like a machine or device.

Configure Metadata as Portal Search Facets

1. In the Content Library, ensure that you are working in the master branch and go to your main portal sitemap.
2. Open the main portal sitemap.
3. In the map tree pane, click the Gear button and set your options like this:
   1. Set Icons to On.
   2. Set Show Elements to All.
   3. Set Element Names to Full.

   The map tree now shows color-coded elements with full element names. This view enables you to easily identify and modify all elements in your sitemap.

4. Expand the sitemeta element, right-click the config.json element, and select Show file in Content Library.

5. In the Content Library, right-click the config.json file and select Edit Source.
6. In the Source Editor, press Ctrl/Cmd > F and search for facets.

   The facets parameter you are looking for is included in the search parameter.

   JSONCopy

   "search": { "ref": "href", "fields": [ "href", "shortDescription", "title" ], "sections": [ "sitesection" ], "facets": [ "Information_Type", "Area" ] },

   "search": {
           "ref": "href",
           "fields": [
               "href",
               "shortDescription",
               "title"
           ],
           "sections": [
               "sitesection"
           ],
           "facets": [
               "Information_Type",
               "Area"
           ]
       },

7. Open the CCMS in a new tab or window, and from the Main Menu in the top-left corner select Metadata.
8. Scroll to a metadata you want to enable as search facets and copy the value in the Name column.

9. Go to the config.json file and paste the copied value under the facets parameter.

   By default, the order in which you add the metadata name values to the config.json file defines their order in portal. Child facets grouped under a metadata name value are ordered alphabetically in portal. If name values start with numbers, they are listed first.

   Tip:

   If you want to override the default order of facets, or child facets, see Change the Order of Search Facets

   Important:

   If you need to add multiple name values to the facets parameter, ensure they are separated with a comma like shown in the example. Note that there is no comma after the last parameter value.

   The value Category copied from the Name column is pasted inside quotation marks ("") under the facets parameter.

   JSONCopy

   "facets": [ "Category", "Area" ]

   "facets": [
               "Category",
               "Area"
           ]

10. Populate the facets parameter with name values for each metadata you want to enable as a search facet.
11. Click Save.

If the deployment from the master branch to Heretto Portal uses the active sync deployment type, your facets are visible in the portal environment associated with your master branch instantaneously. If the deployment uses manual deploy, a user assigned the Administrator role in the CCMS needs to publish it to portal from the Deployments interface available under the Main Menu .

If you want to arrange your search facets in a specific, custom order, see Change the Order of Search Facets.

Push all files you modified from the master branch to other branches associated with your portal environments to ensure your changes are present there. Use the Branch > Replace mechanism. Branch > Merge doesn't push CCMS metadata. Then, publish your changes from the Deployments interface (Administrators only).

You can rearrange the order of search facets by overriding the default sorting order.

1. Open the main portal sitemap.
2. In the Content Library, ensure that you are working in the master branch and go to your main portal sitemap.
3. In the map tree pane, click the Gear button and set your options like this:
   1. Set Icons to On.
   2. Set Show Elements to All.
   3. Set Element Names to Full.

   The map tree now shows color-coded elements with full element names. This view enables you to easily identify and modify all elements in your sitemap.

4. Expand the sitemeta element, right-click the config.json element, and select Show file in Content Library.

5. In the Content Library, right-click the config.json file and select Edit Source.
6. In the Source Editor, press Ctrl/Cmd > F and search for facets.

   The facets parameter you are looking for is included in the search parameter.

   JSONCopy

   "search": { "ref": "href", "fields": [ "href", "shortDescription", "title" ], "sections": [ "sitesection" ], "facets": [ "Information_Type", "Area" ] },

   "search": {
           "ref": "href",
           "fields": [
               "href",
               "shortDescription",
               "title"
           ],
           "sections": [
               "sitesection"
           ],
           "facets": [
               "Information_Type",
               "Area"
           ]
       },

7. If you already have the facets parameter in the search parameter, insert the facetsAdvancedSettings parameter immediately after the facets parameter.

   The facetsAdvancedSettings parameter requires the order parameter. You define the actual order of your facets and child facets there.

   Important:

   Be sure to insert a comma on the square brace that is right before the new facetsAdvancedSettings parameter, as illustrated in the example.

   The facetsAdvancedSettings parameter requires the order parameter. You define the actual order of your facets and child facets there.

   JSONCopy

   "search": { "ref": "href", "fields": [ "href", "shortDescription", "title" ], "sections": [ "sitesection" ], "facets": [ "Information_Type", "Area" ], "facetsAdvancedSettings": { "order":{ "Area": [], "Information_Type": [], "Grade_Level": { "grade_1": [], "grade_2": [], "grade_3": [], "grade_4": [], "grade_5": [], "grade_6": [], "grade_7": [], "grade_8": [], "grade_9": [], "grade_10": [], "grade_11": [], "grade_12": [] } } }

   "search": {
           "ref": "href",
           "fields": [
               "href",
               "shortDescription",
               "title"
           ],
           "sections": [
               "sitesection"
           ],
           "facets": [
               "Information_Type",
               "Area"
           ],
   	"facetsAdvancedSettings": {
                "order":{
                     "Area": [],
                     "Information_Type": [],
                     "Grade_Level": {
                         "grade_1": [],
                         "grade_2": [],
                         "grade_3": [],
                         "grade_4": [],
                         "grade_5": [],
                         "grade_6": [],
                         "grade_7": [],
                         "grade_8": [],
                         "grade_9": [],
                         "grade_10": [],	
                         "grade_11": [],
                         "grade_12": []
                  	  }            
                }
           }

   In this example, we have changed the order of Area and Information_Type. We have also added a new metadata facet for grade levels. The default sort order for a list such as this would be grade_1, grade_10, grade_11, grade_12, grade_2, and so on. The facetsAdvancedSettings parameter enables sorting the grades by their logical order instead of their name in the CCMS.

8. Add as many metadata facets to the order parameter as needed.
   Important:

   The facetsAdvancedSettings parameter overrides the facets parameter. If you're using the facetsAdvancedSettings parameter, be sure to also include the configuration that you previously added to the facets parameter.

9. Be sure to save your changes to the config.json file.

If the deployment from the master branch to Heretto Portal uses the active sync deployment type, your facets are visible in the portal environment associated with your master branch instantaneously. If the deployment uses manual deploy, a user assigned the Administrator role in the CCMS needs to publish it to portal from the Deployments interface available under the Main Menu .

Push all files you modified from the master branch to other branches associated with your portal environments to ensure your changes are present there. Use the Branch > Replace mechanism. Branch > Merge doesn't push CCMS metadata. Then, publish your changes from the Deployments interface (Administrators only).