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.

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

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 account to a Data Steward role.

 

From now on, a logged in Administrator carries a role of Data Steward for the Customer Data Domain subject 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.

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.

Create 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 creations, you will be sent to an Import/Export 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 subject 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 subject 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 to a new glossary

Go to an Import/Export tab 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. Navigate through breadcrumbs at the top of the screen to a Customer Data Glossary and click on Edit Production Copy. You will see the imported data. Click on any of the terms to see what was imported.

Our spreadsheet only contained term names and definitions. You can capture a lot more information now that your glossary is managed by TopBraid EDG. Click on the Edit button to see all available pre-built fields. 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 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

In the Filter window type Customer. Notice that Customer ID term doesn't have any definition.

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.

Click on Start Workflow in the top menu of the right pane. Name the workflow as "Additional description" and click on Submit button.

Click on Edit Working Copy to open an edit view of the data. Find again a Customer ID record and 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 right top corner of the right pane. This can also be done by seeing a History Report in the Reports pane in the management panel o f the Customer Data Glossary.

A new glossary terms can be created by clicking on a New button at the top of the left pane. We'll leave this task as an exercise for you.

Customizing glossary terms metadata

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 . For information on creating a new ontology, see Create New Ontology in the User Guide.

 

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  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 create a "property shape".

Adding a property shape

Click on the far right icon (blue rectangular frame with a plus sign) in the right top corner of the Class Hierarchy pane to create a restriction on a new property. Notice that we already know which property we'll be describing. The reason why is that we had origin code property highlighted in the Class Hierarchy view. If you prefer to create a property shape for other property you can simply change the property name in a Property to constrain field. Click OK.

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

Data export

Glossary data can be exported in full or defined subsets of data defined through search criteria. After finding the reference dataset you need, click the dataset's Export tab to view the available exports.

 

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 View Production Copy link (or Edit Production Copy—the available link will depend on access granted to you for this dataset) to create a new export after performing a search of your choice.

You will see a page that contains a grid with the glossary data, and a review form on the right. When you click on a blue bar on the left the Search pane will display. All the panels are resizable.

Click on Advanced Search to see all properties that can be searched for glossary terms.You can use it to filter out only the terms you want to export.

Let's find all glossary terms that don't have definitions added. Click on a blue triangle on the right from the definition field. A menu of different options of how we want to filter the definition will appear. Choose no value as we want to make sure we want all terms that don't carry the definition. Click Search button at the bottom of the search pane. Currently there is only one glossary term without definition and it is a Customer ID.

 

You can export this search, by clicking on a gear menu button located next to a Reset button in the search pane. A list of different export options for this search will appear.

Saving and reusing searches

You may want to reuse your search results in the future. You can save the search criteria by clicking on button located  on the right bottom corner of the search pane. 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, click on a button. 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.

Saved searches can also be accessed from the Import/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.


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

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 were involved some workflows, you can see a list of workflows 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