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 text 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.

  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. This will also require separate uploading of the EDG samples project: sample.teamwork.topbraidlive.org, from TBC-ME.

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.

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 it 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.

A 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 at the top right of the page. 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 Loyalty Program" 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 terminalogy:

  • 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 working copy, they will only be visible in that working copy. EDG users with the appropriate permissions can choose between making changes directly to a glossary and using workflows to make and review changes.

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. Name the workflow as "Customer ID description" and click on Submit button.

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 the "This working copy is governed by the Basic workflow and is about Customer ID" at the top of the page.

This will open a form for Customer ID. Click on an Edit button in the right top menu of the right pane. The editor allows to add a lot more information that is being presented in the View mode. Add the following definition in the appropriate field: "Customer ID is a 5 character alphanumeric field exactly identifying a customer" and click  Save Changes.

 

Note that you can use darker blue bar to extend the right pane more, to give you more place to work on a glossary term. One of the way to see what changes has been made is clicking on a Show History checkbox in the top of the pane. This can also be done by seeing a History Report in the Reports pane in the management panel of the Customer Data Glossary.

Using search criteria

You may want to find other terms that are about customers.

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 Ontology, 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 , an attribute (Datatype property) , a relationship (Object property) or a property shape  to the selected class in the hierarchy.

 

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

We just created a property and related property shape, however, we have not given it any characteristics. We can edit most property characteristics, like cardinality, value type, string constraints, etc. directly after selecting the attribute we created.


In the edit form choose a 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, select the Glossary Term class to see its property shapes, click on the property shape you want to remove from the list of related properties in the middle pane. Select Glossary Term and scroll down the middle pane to find origin code.


Once the property shape is displayed by selecting it from the related property shapes, click on Edit button. Then, set "deactivated" to true for that property shape related to the selected Node Shape/Class.


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 Terms tab and select one of the glossary terms. If you click on Edit, you will see the new property appear amongs the available fields.

 

We can't see this property in a View mode, as the property has no value. Once you enter a value (in the Edit mode), the property will also show up in a View mode. 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

Searches can be created in the tabular view of any asset collection type by setting Filters and Columns. An example showing a search of Glossary Terms for those containing "budget" in their descriptions is shown in the following screenshot. You may want to save and reuse searches and can do so as shown by selecting the icon that is three dots. A pop-up windownwill request you to give a name to your search. Click OK to save your search. In order to reuse a previously saved search, you can select Open Saved Search and 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 in a search pane of your EDG, whereas Service URL can be used as a RESTful web service call to invoke the search. Note that these searches are also available under the Export tab, selecting Export using Saved Search.



The resulting data can be exported directly from the table by clicking on Export results to CSV, or JSON or TSV. Note that an additional capability under the Export button in the table itself is to export to Excel.

Data export

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 create a new export after performing a search of your choice.

Saved searches can also be accessed from the Export tab. In the Export section, there is an Export Saved Search option, that will give you access to the same functionality, as mentioned above. However, the results are presented a bit differently, as in this case saved searches cover all saved searches, both from production and working copies.

Export Saved Searches will list all searches saved, including a description of the fields they include. The format for exporting the saved search can be selected by using the the Result Format field. Formats include CSV/TSV XML and JSON.

Click the Export button with Text/CSV result format selected to get a comma-separate value file that you can either save or open in Excel.

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 is set at text/csv, but can be manually modified to any of the export formats supported by Saved Search.

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.

To see assets that have been mapped to a glossary term, select the term and in the form displaying its information click on Usages in Other Collections.

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. Your EDG administrator will be able to configure the scope of the search (what is being indexed for searching) as well as how much detail is presented on the search result page. By default, you will see only a name (label) of the returned resources.

In the search results page, you will see search facets on the left that will help you further filter out the search results. Facets are configurable by the administrator.

Next to each search result, you will see:

  • More link that will take you to the glossary (or any other appropriate "home" asset collection if your result is not a glossary term)
  • 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 a Glossary

While this section can serve as a standalone tutorial, it assumes that the Customer Data Glossary has already been created.

On the Home page, in the Glossaries section you will see a list of glossaries you have access to. This list can be long, especially in large organizations with lots of different glossaries. To find a specific dataset, navigate to a Find Asset Collection located in the main menu on the left of the screen and start typing the name of the asset you are looking for. Click Search and the results will show up in a list.

Navigate to the collection by simply clicking on a result or using an Edit button.

If you know of collections (e.g., ontologies or glossaries) in your EDG system that do not appear in the search, you might not have the appropriate viewing or editing privileges for them. Each such collection requires a manager to provide access by setting you (or your security role) as a viewer, at least. See the collection type's User Roles utility documentation for details about these steps.

The Filter Form in the left pane lets you enter more specific search criteria against a number of pre-selected fields. You can use a combination of search criteria. For example, a description of the dataset, a metadata about it. You can also use the Search Any Text field to enter a text string that by default will be matched against any textual information contained with the reference dataset. (Your administrator may configure this feature to only search over a subset of text fields, such as the name and description of a reference dataset). If you need to target your text search to only one specific field such as description, click the triangle button to the right of the field to get menu options, select "text contains" and enter "country". Otherwise, unlike Search Any Text which assumes partial match, it will try to find an exact match—for example, a description that contains only the word "country".

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. 

Exporting Glossaries

As a Business Analyst you may need to create a report that include specific glossary terms. Look at the Data Export section of this document for more information.

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