Managing a Business Glossary

Business glossaries are managed by the data stewards or the data governance 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

To access the Create Glossary panel, follow these steps:

  1. On the Home tab of a data catalog, click Glossaries. Alternatively, click + from tabs and select Glossaries.
    Note

    After creating a data catalog instance, when you access the Home tab for the first time, you can find the Glossaries tile on this page. When you click the Create Glossary tab in this tile, you are navigated to the Create Glossary panel
  2. In the Glossaries page that appears, click Create Glossary.
    The Create Glossary panel opens.
Creating a Glossary

Here's how you create a glossary:

  1. In the Create Glossary panel, do the following:
    • Name: In this field, enter a unique name for the glossary.
    • Description: In this field, specify the purpose of creating the glossary.
  2. Click Create.
Creating a Category

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

Here's how you create a category:

  1. On the Glossaries page, click the glossary for which you want to create a category.
    The glossary details page appears.
  2. Click the Create Category tab.
  3. In the Create Category panel that appears, do the following:
    • Name: Enter a name for the category.
    • Description: Enter a name for the category.
    • Owner: Select the owner of the category from the list.
    • Status: Select a status from the list. The available options are:
      • New
      • Approved
  4. Click Create.

The category is created and is listed in the glossary details page.

After you create a category, it is listed in the Hierarchy pane of the glossary details page. You can create terms within this category. You can also nest a category under another one.

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. On the Glossaries page, click the glossary for which you want to create a term.
    The glossary details page appears.
  2. In the Hierarchy pane of the glossary details tab, click the category where you want to create a term.
  3. In the category details page, click Create Term.
  4. In the Create Term panel that appears, do the following:
    • Name: Enter a name for the term.
    • Description: Enter a name for the term.
    • Owner: Select the owner of the term from the list.
    • Status: Select a status from the list. The available options are:
      • New
      • Approved
  5. Click Create.

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

After the term is created, it is listed in the Hierarchy pane of the glossary details page. 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 page, the information is displayed in the Hierarchy pane and the 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 to expand, and Collapse All to collapse all the nodes available in the glossary. You can also use the search bar to search for categories and terms.

  • Summary: The Summary tab displays the default properties such as, the name, owner, status, and description of the glossary, category, or term.

  • Linked Terms: When you click a term node in the hierarchy section, the details page on the right pane displays the Linked Terms tab. You can view the parent and children terms linked to the selected term.

  • Linked Objects: When you click a term node in the hierarchy section, the details page on the right pane displays the Linked Objects tab. You can view all the data entities and attributes linked to the selected term.

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

  • Edit: Click this link to edit the default properties such as the name and description of a glossary.
  • Create Category: Click this button to create a category within the glossary.
  • Import: Click this button to import a glossary from your local system.
  • Export: Click this button to export a glossary and save it as a file in your local system.
  • Delete: Click this button to delete a glossary.

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

  • Edit: Click this link to edit the default properties such as the name and description. of a category.
  • Create Category: Click this button to create a category within another category.
  • Create Term: Click this button to create a term in a category.
  • Delete: Click this button to delete a category.

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

  • Edit: Click this link to edit the default properties such as the definition and properties of a term.
  • Link to Parent: Click this button to link a term to its parent term.
  • Link to Children: Click this button to link a term to its children terms.
  • Delete: Click this button to delete the term.

Editing a Business Glossary

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

Editing the Default Properties of a Glossary

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

  1. On the glossary details page, in the Hierarchy pane, select the glossary that you want to edit.
  2. In the Default Properties section of the Summary tab, click Edit. The Edit Harvested Properties panel opens as an overlay.
  3. Make the required changes. You can modify the following fields:
    • Name
    • Description
    • Owner
    • Status
  4. Click Save Changes.
Editing the Custom Properties of a Glossary

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

  1. On the glossary details page, in the Hierarchy pane, select the glossary that you want to edit.
  2. In the Custom Properties section of the Summary tab, click Edit. The Edit Custom Properties panel opens as an overlay.
  3. Make the required changes and click Save Changes.
Editing the Default Properties of a Category

Here's how you edit a category:

  1. On the glossary details page, in the Hierarchy pane, select the category that you want to edit.
  2. In the Default Properties section of the Summary tab, click Edit. The Edit Harvested Properties panel opens as an overlay.
  3. Make the required changes. You can modify the following fields:
    • Name
    • Description
    • Owner
    • Status
  4. Click Save Changes.
Editing the Custom Properties of a Category

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

  1. On the glossary details page, in the Hierarchy pane, select the category that you want to edit.
  2. In the Custom Properties section of the Summary tab, click Edit. The Edit Custom Properties panel opens as an overlay.
  3. Make the required changes and click Save Changes.
Editing the Default Properties of a Term

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

  1. On the glossary details page, in the Hierarchy pane, select the term that you want to edit.
  2. In the Default Properties section of the Summary tab, click Edit. The Edit Harvested Properties panel opens as an overlay.
  3. Make the required changes. You can modify the following fields:
    • Name
    • Description
    • Owner
    • Status
  4. Click Save Changes.
Editing the Custom Properties of a Term

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

  1. On the glossary details page, in the Hierarchy pane, select the term that you want to edit.
  2. In the Custom Properties section of the Summary tab, click Edit. The Edit Custom Properties panel opens as an overlay.
  3. Make the required changes and click Save Changes.

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 list, 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 list, 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 subcategory to another category to ensure accurate categorization of the business vocabulary of your organization. When you move a category or a subcategory, all the terms associated with it are also moved to the new category. To move a category or a subcategory, 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 subcategory.
  3. In the glossary details page, based on how you want to move the category or subcategory, do one of the following:
    • Move the category or subcategory using drag and drop method:
      • From the Glossary Hierarchy, select the category or subcategory you want to move, and then drag and drop it into the category of your choice. Repeat this step for all the categories or subcategories that you want to move.
    • Move the category or subcategory using the Move button:
      1. From the Glossary Hierarchy, select the category or subcategory that you want to move, and click Move.
      2. In the Move Terms and Categories panel that appears, select the check box next to category or subcategory that you want to move.
      3. From the Target Category list, 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 the Microsoft 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:

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

Here's how you export a glossary:

  1. From the Home tab, click Glossaries.
  2. From the glossaries list, click the glossary name that you want to export.
  3. On the glossary details page, from the Hierarchy section, select the glossary node.
  4. Click Export.
  5. In the dialog box that appears, review the note, and click Proceed.
The glossary exports as a Microsoft Excel file. Save the file to your local system.
Importing a Glossary

Here's how you import a glossary:

  1. From the Home tab, click Glossaries.
  2. From the glossaries list, click the glossary name to which you want to import.
  3. On the glossary details page, click Import.
  4. In the dialog box that appears, review the note, and click Proceed.
  5. Using the file browser, locate the Microsoft Excel file that you want to import, and click Open.
An import glossary job is triggered. If the import file is small, the job completes 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 file are imported into your glossary.

Deleting in a Business Glossary

Deleting Glossaries

Here's how you delete a glossary:

  1. From the Home tab, click Glossaries.
  2. From the glossaries list, click the glossary name that you want to delete.
  3. On the glossary details page, click Delete.
  4. In the Delete Glossary confirmation box that appears, type Delete to confirm.
  5. Click Delete.

The glossary gets deleted. All the categories and terms within the glossary are also deleted.

Deleting Categories

Here's how you delete a category:

  1. From the Home tab, click Glossaries.
  2. From the glossaries list, click the glossary name that contains the category you want to delete.
  3. On the glossary details page, from the Hierarchy section, select the category that you want to delete.
  4. Click Delete.
  5. In the Delete Category confirmation box that appears, type Delete to confirm.
  6. Click Delete.
The category gets deleted. All the categories and terms within the category are also deleted.
Deleting Terms

Here's how you delete a term:

  1. From the Home tab, click Glossaries.
  2. From the glossaries list, click the glossary name that contains the term you want to delete.
  3. On the glossary details page, from the Hierarchy section, select the term that you want to delete.
  4. Click Delete.
  5. In the Delete Term confirmation box that appears, type Delete to confirm.
  6. Click Delete.
The term gets deleted.