How to Build a Glossary from Business Process Model?

Why Glossary?

Visual Paradigm's glossary feature lets you create and maintain a set of domain specific terms used in your model. It establishes a common protocol in language use for readers to understand a model by providing descriptions to key terms and phrases, explaining detailed concepts, describing abbreviation, etc. It also helps modelers on the same team establish and maintain a unified glossary when creating different kinds of models for any parts of a business/system.

Why Identify Glossary Terms Directly from Business Process Model?

We know that the responsibility of a business process model is to describe a business process from business perspective. For this reason, it would be a good place to identify key terms that are relevant and important to the business. Therefore, we will focus mainly on identifying glossary terms from BPD, even though the same technique can be applied to any kinds of models.

Best Practices of Defining Terms

The way how terms are defined does affect how well readers understand the idea you want to express through modeling. In this section, we are going to provide you with some guidelines on how to define terms in descriptive and meaningful manner.

Be Descriptive

Never try to describe a phrase just by adding a few more words to itself. This won't help readers in understanding what a phrase/term means exactly. Try to give it solid information that is relevant to the business domain. Ultimately, readers should be benefitted by reading the definition.

Term	Bad Definition	Good Definition
Place Order	Place an order	The process of submitting a purchase order by customer via the online shop. An order contains information of the product to purchase, the quantity and the price.
Deliver Goods	Deliver goods to user	Ship the items customer purchased through local courier service.

Never Describe a Phrase by Reversing the Order of Words

Do not just describe a phrase by reversing the order of words. This does not give too much meaning to the phrase.

Term	Bad Definition	Good Definition
Customer Service Assistant	The assistant for customer services	The person who provides customer with different kinds of support (e.g. online live chatting, telephone conversation)
System Inspector	Inspector of System	The person who performs a series of planned testing to check for system defects.

Avoid Describing a Term by Just the Term Itself

Readers look up the definition of a term because he/she doesn't know what it means. If we reuse that same term in the definition, this would probably not be very helpful in clarifying things.

Term	Bad Definition	Good Definition
Order	An order submitted by customer	A document that lists the products to purchase, the quantity, the price and the terms.
Customer	A customer of the shop	The person who has purchased a product and settled the payment.

Identify Glossary Terms from BPD in Visual Paradigm

Identify Terms from BPD

Download The True Aqua Distilled Water Company.vpp. You can also find this file at the bottom of this tutorial, under the Resources section.
Open the downloaded project file in Visual Paradigm. You can open a project by selecting Project > Open from the application toolbar.
Open the BPD Distilled Water Ordering Process. Let's identify words or phrases in the diagram to become glossary terms.
The pool at the very top of the diagram is named Customer. As mentioned before, readers may not know whether customer here stands for a registered user or anyone who wants to order distilled water. Let's define Customer and make it a glossary term. Double click on the pool. Right-click on the word Customer and select Add "Customer" to Glossary from the popup menu.
You should see a message appears on the status bar, telling you that the term Customer has been added into the glossary grid. Click on the link of glossary grid to go there. If you have missed that, do not worry. You can open the glossary grid by selecting Modeling > Glossary > Glossary Grid from the application toolbar.
Glossary grid is where glossary terms are listed. You can check the terms and their definitions in the grid. You can also create and manage terms via the related function buttons on the toolbar at the top of the glossary grid. Now, describe the term Customer. Right-click on the term and select Open Term Editor from the popup menu.
Enter the definition of term in the Definition field: The person wanting to purchase distilled water, either as a first-time buyer or someone who has purchased before..
We can use different texts (via aliases) to refer to the same term. This helps to avoid redundancy in creating multiple terms carrying the same meaning. Let's say some of the end users may call a customer a "buyer". Let's add an alias called "buyer". Click Add on the right in the Aliases section (which is located at the top of the term editor).
Enter Buyer in the input window and confirm. Buyer is now an alias of the term Customer.
Go back to the glossary grid by selecting Modeling > Glossary > Glossary Grid from the application toolbar. You can see the alias and description (i.e. definition) as well.
Now, let's add a label for the term. Right-click on the term Customer in the grid and select Open Customer Specification... from the popup menu.
To add a label, click the plus button next to the Label field.
In the Add Label window, click New Label... at bottom left. In the popup window, enter the name of the label: Human Participant. Click OK to confirm.
Click OK in the Add Label window. The label is added to the term.
Click OK in the Term Specification window to return to the glossary grid. You can see the label in the grid, too.
Now, go back to the BPD. You can see the word Customer highlighted across the diagram. When a reader wants to know what customer means, he can open the definition from the term. Let's try. Move the mouse pointer to any Customer shown in the diagram. Press the <Ctrl> key and click on the word. This opens the glossary grid with the term Customer highlighted.

Identify Terms via Textual Analysis

Besides identifying terms from BPD or creating terms directly in the glossary grid, you can also identify terms via textual analysis. This helps you seek business terms that need to be explained from any documents collected from end users.

Open Textual Analysis1 in the same project. You can find and open a diagram in Project Browser by selecting View > Project Browser from the application toolbar.
Let's say the text ordering hotline is worth explaining. Select it. Right-click on the selection and select Add "ordering hotline" to Glossary.
You can then find the term ordering hotline in glossary grid.

Let's identify the following terms from textual analysis.

Name	Alias	Label	Documentation
Ordering hotline			Hotline is established for both inquiries and ordering by telephone.
Email			Customers can send an email to order water or to ask questions about water ordering.
Customer service assistant		Human Participant	The person who receives and processes customers' order requests. He is also responsible for answering user's inquiries.
Logistics Department			A department that is responsible for managing and executing the delivery of distilled water.
delivery	shipment		The process in which workers ship the distilled water to customers. It should be done on every Wednesday.
workers	Sales representative	Human Participant	The people who deliver distilled water to customers. Workers usually work in teams. Each team has about 3 to 4 workers.
schedule			A written notice that shows the details of a delivery, which includes the delivery address, workers in charge and the number of distilled water bottles to deliver.

When you are done adding the glossary terms, the glossary grid should look like this:
grid content

Export Glossary to Excel

The term definitions can help modelers in the same team establish and maintain a common vocabulary set, when modeling and communicating with each other. You can also make use of the Excel export function to produce a soft copy of the glossary and share it with other team members.

Open the glossary grid.
Click the Export to Excel button from the toolbar within the grid window.
In the Export Excel window, specify the output path to save the Excel file in.
Keep the other settings unchanged. Click Export at bottom right.

As a side note, importing changes made in Excel back to the glossary in Visual Paradigm is possible. If needed, readers of the glossary can make changes in Excel. After that, click the import button in the glossary grid (in Visual Paradigm) to import the Excel file back to Visual Paradigm. The import button is just next to the export button.