Child pages
  • Getting Started - EDG Business Glossaries
Skip to end of metadata
Go to start of metadata

Introduction

A glossary is collection of terms in a particular domain (i.e., field or subject) of knowledge with the test definitions for those terms. Unlike dictionaries, which are more general collections of words, glossaries only concern themselves with terms that will enhance one's comprehension of a certain topic. Glossary terms are often highly specific to a particular business subject or area of operation. They could be thought of as a 'jargon'. Just about any business activity and organization you can think of has its own jargon to go with it - from professional disciplines to operational activities.

A business glossary goes beyond just a list of terms. Linking terms to IT assets establishes a connection between business and IT and enhances organizational collaboration. Glossary lets you create and manage a common vocabulary of terms important to your organization to ensure clear communication and improve productivity. These terms can be categorized in a way that is relevant to your organization. Multiple glossaries can be developed, interlinked, searched and explored. Valid definitions of values and business rules can then be managed and made available across the organization. 

Glossary terms can be a 'flat' alphabetical list or they can be organized into hierarchies. In TopBraid EDG, the primary user interface (UI) for viewing and editing glossary terms looks like a spreadsheet. When working with glossaries, users can also switch into a hierarchical view and pick any defined relationship between terms to present them as a taxonomical tree. TopBraid EDG also supports a category of vocabularies that are called "taxonomies". Depending on your licensing, you may see this category of asset collections in your installation of EDG and, as a result, may wonder about the difference between glossaries and taxonomies and when to use each - especially, if your terms are organized hierarchically. Unlike glossaries, taxonomies always assume that terms are organized and presented as hierarchies and that the hierarchical relationship between them is "broader concept" which is defined by the SKOS standard. SKOS doesn't use the word "term" that is common to business glossaries. Instead, it uses the word "concept".

Even more importantly, glossaries are designed to improve understanding of data’s context and usage. Glossary terms not only have descriptions of their meaning, but they also define business context of use and can be linked to the underlying technical metadata to provide a direct association between business terms and data sources and data elements. In TopBraid EDG, glossary terms include description of business rules and permissible values - both, in plain English as well as in structured, executable rules that are used to automate connections between data elements and business terms. They may also connect to reference datasets and enumerations that hold lists of values specific to a given term such as "customer status". Taxonomies, on the other hand, describe some domain of knowledge in general. They are often focused on providing a rich set of synonyms that are used in search, text mining and document classification.

This document is organized by roles showing how:

  • Data Stewards, Business Stewards or Subject Matter Experts can create and modify glossaries, import and organize glossary content and manage information about a glossary. We also describe how fields available for describing glossary terms can be configured by using ontologies.

  • Business Analysts and other users can consult EDG to learn more about terms important to their work and how they connect to data.

Accessing the EDG Application

To work through this guide, use a browser to access the EDG web-application running in one of the following environments.

  1. Create an EDG trial evaluation at TopQuadrant, and run EDG from the TopQuadrant servers. Submit an EDG evaluation request or contact TopQuadrant.

  2. Use TopBraid Composer - Maestro Edition (TBC-ME), and run its demonstration version of EDG. Download and install TBC-ME. If using sample data then, this will also require separate installation of the EDG samples project.

  3. Install EDG on a server accessible to your network (which could also be a local Tomcat server, via localhost). For a custom install, contact TopQuadrant and see EDG Server Installation and Integration. If using sample data, this will also require separate installation of the EDG samples project.

For the TBC-ME option, launch TBC-ME and then start the demo version of EDG via the top menu: TopBraid Applications > Open TopBraid EDG. Browse to  http://localhost:8083/edgLogging in as Administrator requires no password for the demo version. All asset collection types are available in the demo version.

For the other two options, the system administrator or TopQuadrant will provide you with a URL, a username, and a password. Browse to the URL and log in. Server licensing will determine the availability of the various asset collection types.

The EDG User Interface

For a basic orientation to the user interface, see EDG User Guide - UI Overview .

You will always see the collapsable left hand side Navigator that will help you navigate between asset collections and pages of interest. Menu sections in the Navigator are also collapsable and expandable. A "hamburger" menu button in the header offer an alternative approach to quick navigation between different glossaries.

Glossary Management

Setup Governance Areas and Roles

Governance areas organize glossaries (and other EDG asset collections) according to either business-oriented or data-oriented concerns. The areas can have associated governance roles, which help business teams to coordinate their management of the area's collections via defined workflows. For additional details, see the Governance Model Overview.

We will first create a data subject area and assign a goverance role to it. Click GOVERNANCE MODEL > Governance Areas > Create Data Subject Area. Create the Customer Data Domain subject area and click OK.

Once you added Customer Data Domain subject area add Data Steward governance role from a drop-down menu.

Assign Administrator a Data Steward role.


From now on, a logged in Administrator (user ID) carries a governance role of Data Steward for the Customer Data Domain area. The scope of this role is any asset collection in the area. Governance roles can also be defined at the level of an individual glossary and even individual asset. They not only document responsibilities, but also determine what users can do as part of the workflows that are defined using governance roles.

Getting Started for the Steward

As a steward you need to be able to create and maintain glossary datasets. This part of the document will briefly explain you how to do that.

Creating, Populating and Changing a Business Glossary

Creating a new glossary

You can create a new glossary:

  • Directly from the Governance Areas page by clicking on the area your new glossary should belong to and then choosing Glossary in the Chose Type drop down. Your newly created glossary will be automatically connected to the subject area.
  • Alternatively, you can click on the Glossary asset collection in the left menu and click on the "Create New Glossary" in the top of the screen.

In either case, the Create dialog will ask you for the glossary name (label). You can also add a description and specify a "default namespace".

The default namespace is used to formulate URIs for the glossary terms. Every asset managed by TopBraid EDG has a globally unique web identifier - a URI. People and applications can link and refer to this URI in a similar way to how web pages can link and refer to each other. URIs can be dereferenced by people and applications. This means that submitting a URI will return either a web page with its information or a data object representing it.

You can also select the preference for your instance data URI settings at the collection level. This will override the default set by and Administrator.

TopBraid EDG will pre-populate the default namespace field with a default that you can change. Lets name our glossary "Customer Data Glossary" and add the following description: "A multi division effort to consolidate all customer related terminology." Click on a Create Glossary button.

After creation, you will be sent to an Import tab, where you can choose one of the ways of importing your data to a newly created dataset.

Viewing and changing information about a glossary

If you used the second method of creation, you may want to add more metadata about your new glossary such as the governance area it belongs to.

You can do this either prior to importing data into our glossary or at any point after importing. To update glossary metadata, go to Settings tab and at the bottom of the screen, in the Metadata section, add a Customer Data Domain to a subject area. Save changes. Note that an asset collection can belong to multiple governance areas.

In the Settings tab, you will also see other information about the Glossary - such as its URI, what other asset collections include it, etc. Just like terms in the glossary will have a unique URI, each glossary will also be identified by a URI which is auto-generated by EDG.

Importing data into a new glossary

If you are not already on the Import tab, click on it and select Import Spreadsheet using Pattern. Then, click the Browse button to select the spreadsheet. (Download the Sample Customer Data Glossary.xlsx spreadsheet to get a local copy to import.). Choose a Glossary term as an entity type and click Next button.

In the next page choose the spreadsheet type form the selection menu. Based on the sample 6 rows coming from your spreadsheet, notice that data from the spreadsheet doesn't follow any hierarchy, thus choose "No Hierarchy" from the menu. Click Next button. In the next screen specify how the columns from the spreadsheet will be mapped. In this example a description column will be mapped to a definition and make label column as unique ID. Click Finish to import the data.

You should be able to see "Completed Spreadsheet Import" screen. Click on Terms tab to see the imported data. Note that you can collapse the left hand side Navigator to get more space.

You can change the columns of the displayed table by clicking on the Columns button. It lets you control what fields to display in the table. Our spreadsheet only contained term names and descriptions. You can capture a lot more information now that your glossary is managed by TopBraid EDG. For now, let's add the description column since this is the only additional, not already displayed data that we have.

Buttons on top of the table let you create a new term, delete selected term or a group of terms, edit information about a group of selected terms, export data in the table and more. To change information about a single term, double click on it.


Form with its information will open in a new browser tab.

For example, you can add business rules about the term and link it to other enterprise information such as business activities. You can also connect terms to each other and organize them into hierarchies. To get into a hierarchical view, click on a tree icon in the header - to the left of the "Go to". You will be able to pick any relationship defined for glossary terms to see and work with a tree display.

If the field you want to modify already contains some information, instead of clicking on the Edit button, you can use inline editing. Hover to the left of the field's value to see a pencil icon. Click on it to start in-line editing.

Other users can also link or map to this term. For example, catalogs of data sources can map database columns and table to a term. To see any assets that are not part of this glossary, but are using and referring to the terms in the glossary, click on Usages in Other Asset Collections link.

Creating a new term

Select New at the top of the table.

The Create dialog will require you to enter a name (label) of the new term. You will also be able to see the auto-generated term URI and modify it if necessary. You will be able to select a sub category of a Glossary term, if desired. EDG's pre-built glossary model distinguishes between glossary term, business term, technical term, industry term and a PII term. Your organization may decide to create your own sub types of terms and/or to disable the sub types included in EDG.

Type "Customer ID" as the new term label. Select Business Term from the drop down by clicking on the Glossary Term. Click Confirm.

Your new term is created. You will see a form where you can enter more information about the term.

Editing glossary terms via workflows

Click on the table column heading description to sort by description. Notice that Customer ID term doesn't have any description.

This could be fixed directly in the glossary or can be done in a context of a workflow (with an associated working copy) that would store the information about changes to the glossary term. This way, all changes go through a workflow process enabling collaboration and better control over data. EDG uses the following terminology:

  • The production copy is the master version of the glossary.
  • working copy is a virtual copy of the glossary created for editing purposes. A working copy gets created when a new workflow starts and is associated with that workflow. Changes you make in the working copy will go through a workflow approval process described in the workflow template. At the end of the process changes typically get published to the production vocabulary.

Several workflows, each with its own associated working copy, may be in progress at the same time as users in various roles make and review changes in those working copies. All working copies can be accessed from glossary's Workflow tab that displays workflows in progress. TopBraid EDG offers a built-in workflow template (called Basic workflow). You can also add custom workflows to EDG. More information about it can be found in the Workflows section 

When you make changes directly in the glossary, your changes will be immediately visible to everyone using the glossary. They will also show up in any working copy created for the glossary.

When you make changes in a context of a workflow, they are kept in the workflow's working copy. Thus, changes will only be visible in that workflow.

EDG users with the appropriate permissions can choose between making changes directly to a glossary and using workflows to make and review changes. You can start a workflow for a glossary as a whole or for a particular term in a glossary. We will do the latter.

Double click on the Customer ID term to have its form open in a new tab. Click on Start Workflow in the top menu of the form. Alternatively, you can select a term in the table, click on the More Actions button and select Start Workflow from the menu.

In the dialog that appears, name the workflow "Customer ID description" and click on Submit button. If your installation has more than one workflow template that is applicable to glossaries, you will get a chance to select the type of workflow. After the workflow is created you will see Workflow Status and Transitions page. You can always come back to this page by clicking in the gear icon in the header (located to the left of the Terms tab).

You know that you are now in the context of a workflow because the color of the header menu changed to yellow. Click on the Customer ID link in blue in the header at the top of the page.

This will open a form for Customer ID term. Click on an Edit button in the right top menu of the right pane. Add the following definition: "Customer ID is a 5 character alphanumeric field exactly identifying a customer" and click  Save Changes.


Click on the Show History checkbox in the header of the form. Checking this option will show you the changes that were made to the currently displayed term.

If multiple terms were changed during the course of the workflow, you can see the entire history of changes by clicking on the Reports tab and then selecting History Report.

Clicking on the gear button to the left of the Terms tab will return you to the workflow status page. Now that you made some changes, you will see more actions available to transition the workflow to the next state. You can Freeze for review and you can also directly Commit changes. The former action will put the workflow in the state where no more changes can be made. It is designed to let responsible parties review the content and either approve or reject it. They could also unfreeze the workflow opening it to further changes. The latter action will complete the workflow and write all changes to the Glossary.

To exit the workflow in progress and come back to the current (AKA production) version of the Glossary, click on the x button to the right of the Customer ID description in the header at the top of the page.

Customizing Glossary Terms Metadata

Creating and including ontologies

Metadata available for each glossary term in EDG is defined in an ontology. If you are satisfied with properties that are provided for glossary terms, then you don't need to modify the glossary ontology. However, you may want to add new fields (properties) or remove existing fields. You can address this by creating an extension to the pre-built TopBraid EDG glossary ontology.

To do so, go to the Ontologies asset collection in the Home menu (use breadcrumbs to navigate there) and Create New Ontology. You can name it Glossary Ontology Extensions or select another name of your choice.

Include the TopBraid EDG Glossary model in the new ontology. Go to Settings tab and click on an Includes to see the pop-up window. In a pop-up window filter our EDG SHAPES - Glossary (Other) and add it to the includes.


Go to Manage tab and type Glossary Term in the Root Class of Hierarchy. This will set the root of the ontology class tree to Glossary Term and will make it easier for you to focus on your changes.

Creating a new property

Let's add a new property for the glossary terms. We will add a new property origin code that doesn't exist in a current model. Click on Edit Production Copy, then click to select Glossary Term in the tree view. In the right top corner of the tree view choose a green icon representing a datatype property. Name it origin code and click OK.

The colored buttons at the top of the class hierarchy, next to the quick search field, will create a new class , attribute property , relationship property or property shape , view node shapes to the selected class in the hierarchy.

In the edit window add a comment: "A 3 character reference code to owner or " and save the changes.

We just created a property, however, we have not given it any characteristics. In order to add property characteristics, like cardinality, value type, string constraints, etc. we'll scroll down in the edit form of this property. In the edit form set the datatype to be string. Give this string a constraint by specifying min and max length to 3. Specify cardinality by setting up a max count to 1 and choose a group in which this property will be presented in the editor to Glossary Term Metadata. This way we specified that the values of origin code properties can be exactly 1, with the length equal 3 and they are strings. We also made sure that the property will show up in an Edit/View form under Glossary term metadata. After the modifications were made, save the changes. You should see the following screen.

Disabling a property

If you do not want to use any of the predefined properties and want to remove them from the user interface, click on the property you want to remove, then click on the shape information. Once the property shape is displayed, click on Edit button. Then, set "deactivated" to true.

Making ontology customization available to a glossary

Once we created custom modifications we need to make them available to our glossary. Go to a Glossaries asset collection on a Home screen (navigate through breadcrumbs or using the "hamburger menu") and select Settings tab. Click on Includes link, search for Glossary Ontology Extensions and add it to the glossary. After closing a screen you should be able to see the following:

The new property can now be used to describe terms contained in the Customer Data Glossary. You will need to make similar includes for each Glossary that you want to use the new property.

You organization can also decide that these customizations should be automatically available to all glossaries. There is a setting in the Administration console EDG Configuration Parameters page that lets administrators specify that a customization ontology should be included in any newly created glossary.

Click on Edit Production Copy and select one of the glossary terms. You will now see the new property appear among the available fields.

 

As an exercise, add a value to the origin code and save it.

Export, Collaboration, and Other Activities

Some of data stewards' tasks overlap with the tasks of other users. For example, data stewards may build glossary data, but so do subject matter experts, who could be responsible for adding descriptions to the glossary terms. These overlapping activities, including collaboration between users working with glossary data, are covered in the Getting Started Guides for Vocabulary Management package and Reference Data Management package.

Saving and reusing searches

You may want to reuse your search results in the future. You can save the search criteria by clicking on more menu button located  on the right upper corner of the page and selecting Save Search. A pop-up window will request you to give a name to your search. Click OK to save your search.

In order to reuse a previously saved search, select Open Saved Search from the "more" menu. A pop-up window will show a table with saved searches. Select a search of your choice and click Select or copy a Service URL to use it by the other application. Select will recreate the search criteria on the page, whereas Service URL can be used as a web service call to execute the search.

Data export

Glossary data can be exported directly from the table by clicking on Export button.

You get additional export options on the Export tab. This tab includes an option to export all information available in a dataset.

There may also be exports that focus on specific subsets of data; these are accessible from the Export Saved Search or Saved SPARQL Queries links. If there is no export that suits you, click the Terms tab to performing a search of your choice and save it for re-use. Then choose Export.

Export Saved Search option in the Export tab will provide your results in JSON format.

The URL of the saved search is displayed in the Service URL field, including a unique id for the saved search. This URL can be copied as-is and included in any third-party application needing to extract the codes in the saved search. The format will be JSON.

Deleting saved searches

Saved searches can be deleted in the Search view for the dataset. Choose Show saved searches..., select the search to remove and click Delete.

Using glossary terms to provide context for other assets

If you are using TopBraid EDG for Metadata Management you will want to link other assets (for example, data elements) with glossary terms to provide business context to the assets you are responsible for. TopBraid EDG can auto-generate such connections based on the rules declared for glossary terms and other available information such as the information obtained from the data source profiling. You can also manually link other assets to glossary terms by updating their maps to term property. See relevant User Guides for more details.

When configuring Search the EDG, your EDG Administrator may enable semantic suggestions for the maps to term property. With this in place, you can type the term in the search box and instead of searching for the term, select the suggest to see all assets that are mapped to it.


Getting Started for the Business Analyst

Finding a Term

On the Home page, in the Search the EDG box, type your search keyword - for example, Customer. Be sure to check the box for including this collection in Search the EDG from the Manage tab of the collection.

In the search results page, you will see search facets on the left that will help you further filter out the search results.

Next to each search result, you will see:

  • Comments link that will let you enter comments for the stewardship team and see comments entered by other users
  • Icons that will take you diagrams and views for visually exploring information. Depending on the TopBraid EDG packages installed in your environment, you will see different interactive views such as NeighborGram for navigating the connected graph of information associated with a business term, Data Lineage and Data Impact.

Finding your Workflows

If you are involved in some workflows, you will see a list of workflows for which you have pending actions by clicking on My Workflows in a Dashboard section. 

Learning More

You're now ready to explore the User Guide Overview to learn about all the other features available as you use TopBraid EDG. You'll find out how to use working copies for versioning, import more complex spreadsheets, build and view hierarchies and more

 

 

 


  • No labels