Managing a Business Glossary

Business glossaries are managed by the data stewards or the data governace teams of an organization. The data stewards work across teams to define and approve the hierarchy of the terms. In some organizations, such teams follow a thorough process of submissions, reviews, votes, approvals, change management, and so on to manage the glossary terms.

In this section you learn how to create a business glossary and work with it further.

To learn about the concept of business glossary, see Using Business Glossaries.

Required IAM Policies

You can create policies to define how you want your users to access the glossary resources.

View the glossary verb to permission mapping to decide which verb meets our access requirements. For example, INSPECT allows users to view the list of available glossaries and READ allows users to view the details of the glossary and also export the glossary.

Create this policy to allow a group to perform all operations on all the glossaries, categories, and terms available in the tenancy:

allow group <group-name> to manage data-catalog-glossaries in tenancy
Create this policy to allow a group to create, update, and delete terms, categories, and relationships within a specific glossary:
allow group <group-name> to use data-catalog-glossaries in tenancy where target.glossary.key = '<glossary-key>'
Note

You can copy the glossary key for the required glossary from the glossary details page of the user interface.

Create this policy to allow a group to view glossaries and glossary details in a specific compartment:

allow group <group-name> to read data-catalog-glossaries in compartment <x>

Create this policy to allow a group to view the list of all the glossaries available in a specific data catalog in the tenancy:

allow group <group-name> to inspect data-catalog-glossaries in tenancy where target.catalog.id = 'ocid.datacatalog.oc1..<unique_ID>'

Creating a Business Glossary

You use a business glossary to define your concepts across your business domain. Creating a business glossary brings common understanding of the vocabulary used throughout your organization. In Data Catalog, you create categories and terms in a glossary to manage and organize your business concepts.

Accessing the Create Glossary Panel

You access the Create Glossary panel, from the Home tab or the Glossaries tab.

  • On the Home tab, click Create Glossary in the Quick Actions tile. The Create Glossary panel opens as an overlay.

  • On the Glossaries tab, click Create Glossary. You access the Glossaries tab by clicking Glossaries on the Home tab or by clicking + from tabs and selecting Glossaries.

Creating a Glossary

Here's how you create a glossary:

  1. Access the create glossary panel.
  2. In the Name field, enter a unique name for the glossary.
  3. Optionally, in the Description field, specify the purpose of creating this glossary.
  4. Click Create.

The glossary is created and the glossary details tab displays.

After creating the glossary, you can configure the glossary by creating categories and terms and creating links to data objects and links within terms.

Creating a Category

In a glossary, each term must be created within a category.

Here's how you create a category:

  1. On the glossary details tab of the glossary where you want to create a category, click Create Category.
  2. In the Create Category panel, enter a Name and Definition for the category.
  3. Click Save.

The category is created and the category is seen in the glossary details tab.

After the category is created, it is listed in the Hierarchy pane of the glossary details tab and you can create terms within this category. You can also create a category within another category creating nested categories.

Creating a Term

You use terms to classify the harvested data entities and attributes. Each term must be created within a category.

Here's how you create a Term:

  1. Access the glossary details tab of the glossary where you want to create a term.
  2. In the Hierarchy pane of the glossary details tab, click the category where you want to create a term.
  3. Click Create Term.
  4. In the Create Term panel, enter a Name and Definition for the term. A term name must be unique within its category.
  5. Click Save.

The term is created and the term displays in the glossary details tab.

After the term is created, it is listed in the Hierarchy pane and you can classify data assets using this term. See linking glossary terms to data objects.

Viewing a Business Glossary

From the list of glossaries, when you select and open a glossary, the glossary details page appears. On this page, you can view all the categories and terms that are created in the glossary.

In the glossary details tab, glossary information is displayed in the Hierarchy pane and Summary tab.

  • Glossary Hierarchy: The categories and terms created within a glossary are displayed in alphabetical order in a tree navigation list. Expand each category to view terms created within that category. The summary information changes as you click different nodes in the glossary tree. You can use Expand All or Collapse All to expand or collapse all the nodes available in the glossary respectively. You can also use the search bar to search for categories and terms.

  • Summary: The Summary tab displays the Name, Owner, Status, and Description of the glossary, category, or term.

  • Linked Terms: The Linked Terms tab displays when you click a term node in the Hierarchy section. You can view the parent and children terms linked to the selected term.

  • Linked Objects: The Linked Objects tab displays when you click a term node in the Hierarchy section. You can view all the data entities and attributes linked to the selected term.

From the glossary details tab, you can perform more actions based on the node you select in the Hierarchy pane. When you select a glossary node in the Hierarchy pane, you can perform the following actions:

  • Edit the glossary default properties, such as name and description.
  • Create Category within the glossary.
  • Import a glossary by selecting an exported file from your local system.
  • Export the selected glossary and save it as a file in your local system.
  • Delete the glossary.

When you select a category node in the Hierarchy pane, you can perform the following actions:

  • Edit the category default properties, such as name and description.
  • Create Category within the selected category.
  • Create Term within the selected category.
  • Delete the category.

When you select a term node in the Hierarchy pane, you can perform the following actions:

  • Edit the default properties of the term, such as definition and properties.
  • Link to Parent terms.
  • Link to Children terms.
  • Delete the term.

Editing a Business Glossary

You edit a glossary, category, or term to modify their default properties such as name, owner, status, and description, or any custom property that is associated with a glossary, category, or term.

Editing Glossary Default Properties

Here's how you edit the default properties for a glossary:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the glossary you want to edit.
  3. Click Edit from Default Properties. The Edit Default Properties panel opens as an overlay.
  4. Modify the Name, Description, Owner, or Status fields and then click Save Changes.
The glossary details update successfully and the Edit Default Properties panel closes.
Editing Glossary Custom Properties

Here's how you edit the custom properties in a glossary:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the glossary you want to edit.
  3. Click Edit from Custom Properties. The Edit Custom Properties panel opens as an overlay.
  4. Modify the required custom property fields and then click Save Changes.
The glossary details update successfully and the Edit Custom Property panel closes.
Editing Category Default Properties

Here's how you edit a category:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the category you want to edit.
  3. Click Edit from Default Properties. The Edit Default Properties panel opens as an overlay.
  4. Modify the Name, Description, Owner, or Status fields and then click Save Changes.
The category details update successfully and the Edit Default Properties panel closes.
Editing Category Custom Properties

Here's how you edit the custom properties in a category:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the category you want to edit.
  3. Click Edit from Custom Properties. The Edit Custom Properties panel opens as an overlay.
  4. Modify the required custom property fields and then click Save Changes.
The glossary details update successfully and the Edit Custom Property panel closes.
Editing Term Default Properties

Here's how you edit the default properties in a term:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the term you want to edit.
  3. Click Edit from Default Properties. The Edit Default Properties panel opens as an overlay.
  4. Modify the Name, Description, Owner, or Status fields and then click Save Changes.
The term details update successfully and the Edit Default Properties panel closes.
Editing term Custom Properties

Here's how you edit the custom properties in a term:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the term you want to edit.
  3. Click Edit from Custom Properties. The Edit Custom Properties panel opens as an overlay.
  4. Modify the required custom property fields and then click Save Changes.
The glossary details update successfully and the Edit Custom Property panel closes.

Moving Terms Within a Glossary

You can move one or more terms from one category to another to ensure accurate categorization of the business vocabulary of your organization. To move terms from a category, follow these steps:
  1. From the Home tab, click Glossaries.
  2. From the list of glossaries, select the glossary for which you want to move the terms.
  3. In the glossary details page, based on how you want to move a term, do one of the following:
    • Move one term at a time: If you want to move one term at a time, you can use one of the following methods:
      • Drag and drop - From the Glossary Hierarchy, select the term you want to move, and then drag and drop it into the category of your choice. Repeat this step for all the terms that you want to move.
      • Use the Move button - Follow these steps:
        1. From the Glossary Hierarchy, select the term that you want to move and click Move.
        2. In the Move Terms and Categories panel that appears, from the Target Category drop-down, select the category to which you want to move the term.
        3. Click Move.
    • Move multiple terms at a time: If you want to move multiple terms at a time, you can use the Move button that is available in the category details page. To move multiple terms at a time, follow these steps:
      1. From the Glossary Hierarchy, select the category from which you want to move the terms, and click Move.
      2. In the Move Terms and Categories panel that appears, select the terms that you want to move.
      3. From the Target Category drop-down, select the category to which you want to move the term.
      4. Click Move.

Moving a Category Within a Glossary

You can move a category or a sub-category to another category to ensure accurate categorization of the business vocabulary of your organization. When you move a category or a sub-category, all the terms associated with it are also moved to the new category. To move a category or a sub-category, follow these steps:
  1. From the Home tab, click Glossaries.
  2. From the list of glossaries, select the glossary for which you want to move the category or sub-category.
  3. In the glossary details page, based on how you want to move the category or sub-category, do one of the following:
    • Move the category or sub-category using drag and drop method:
      • From the Glossary Hierarchy, select the category or sub-category you want to move, and then drag and drop it into the category of your choice. Repeat this step for all the categories or sub-categories that you want to move.
    • Move the category or sub-category using the Move button:
      1. From the Glossary Hierarchy, select the category or sub-category that you want to move, and click Move.
      2. In the Move Terms and Categories panel that appears, select the chack box next to category or sub-category that you want to move.
      3. From the Target Category drop-down, select the category to which you want to move the term.
      4. Click Move.

Exporting and Importing a Glossary

You export and import glossaries created from one Data Catalog instance to another.

The glossary is exported in Excel file format.

Exported Excel file column headers
  • Type: Specifies if the entry is a category or term.
  • Parent Path: Specifies the path of the parent category. If the entry is the topmost level category, then the parent path column is null.
  • Name: The specified name for a category or term.
  • Status: Specifies whether the status of the category or term, at the time the glossary was exported, is new, approved, under-review, or escalated.
  • Owner (OCID): Specifies the OCID  of the user who owns the glossary category or term.
  • Owner (Name): Specifies the name of the user who owns the glossary category or term.
  • Description: Specifies the description for the category or term.
  • Source Path: Specifies the path of the source term.
  • Relationship Type: Specifies the relationship type as parent:child.
  • Destination Path: Specifies the path of the destination term.
Creating your own import Excel file
  • Define your terms and categories in an Excel sheet named Categories and Terms.
  • The Type, Parent Path, and Name column headers are required to successfully import a Excel format glossary file.
  • To define custom properties, add columns after the Description column. You must use the convention <Namespace>.<Custom Property Name> for custom property column names. Custom Properties is the default namespace.
  • If the Status column is not populated, then default value New is set on import.
  • If the Owner(OCID) column is not populated, then it is set to the OCID of the user importing the file to the glossary.
  • Only the Owner (OCID) column is considered while importing. The Owner (Name) field is not read during import.
  • Relationships can be defined in a separate Excel sheet named Relationships. If any relationships are defined, then the columns Source Path, Relationship Type, and Destination Path must be populated for each relationship.
  • Only Parent:Child relationship type is supported. Any other value is accepted during import but not shown in the user interface.
Note

You can get started with creating your own import file using this Excel template file. The Excel sheet named Metadata has information on creating the import file.

Note

When exporting or importing a glossary, all the data is preserved. Some rich text formatting may be modified or lost.
Format loss details

The following styles may be lost on import or export:

BigFont-FamiliesSpecial ContainerFormattedCited Work
QuoteSample TextItalic Titleto-do listSubscript
SubtitleMarkerBackground color HyperlinksSuperscript
Exporting a Glossary

Here's how you export a glossary:

  1. Access the Glossaries tab.
  2. In the Glossaries list, click the name of the glossary you want to export.
  3. From Hierarchy, select the glossary node.
  4. Click Export.
  5. A Note dialog opens indicating that some rich text formatting might be lost on export. Review the note and click Proceed.
The glossary exports as an Excel file. Save the file to your local system.
Importing a Glossary

Here's how you import a glossary:

  1. Access the Glossaries tab.
  2. In the Glossaries list, click the name of the glossary where you want to import.
  3. Click Import.
  4. A Note dialog opens indicating that some rich text formatting might be lost on import. Review the note and click Proceed.
  5. Using the file browser, locate the Excel file you want to import and click Open.
An import glossary job is triggered. If the import file is small, the job finishes instantly and the imported glossary is displayed. If the import file is large, you can monitor the status of the job from the Jobs tab. When the job is completed successfully, the contents of the Excel file are imported into your glossary.

Deleting in a Business Glossary

Deleting Glossaries

Here's how you delete a glossary:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the glossary you want to delete.
  3. Click More Actions and select Delete.

A notification displays indicating that the glossary is deleted successfully. All categories and terms within the glossary are also deleted.

You can also delete a glossary from the Glossaries tab. In the Glossaries list, click the Actions icon (three dots) for the glossary you want to delete and select Delete. A confirmation window displays. Enter Delete to confirm and then click Delete.

Deleting Categories

Here's how you delete a category:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the category you want to delete.
  3. Click Delete.
A notification displays indicating that the category is deleted successfully. All categories and terms within the category are also deleted.
Deleting Terms

Here's how you delete a term:

  1. Access the glossary details tab.
  2. In the Hierarchy pane, select the term you want to delete.
  3. Click Delete.
A notification displays indicating that the term is deleted successfully. You can also delete a term from the Terms tab. In the Terms list, click the Actions icon (three dots) for the term you want to delete and select Delete. A confirmation window displays. Enter Delete to confirm and then click Delete.