Jump to Menu

How to Build a Glossary from Business Process Model?

Sometimes, when one tries to comprehend a business or a system by studying the related business process models, he/she may have trouble understanding part(s) of the model because some of the element names or documentations are not very clear. This is usually not a language skill issue, but rather one about not knowing the meaning of certain words or phrases specific to the system domain. For example, if you read a BPMN lane called Customer, would you know whether it means someone who has been paid (e.g. a refund), or someone who is required to pay, or just someone who might purchase something but possibly end up not buying in the end? Incorrect interpretation may lead to misunderstanding and developing a system that does not meet customer expectations. In order to ensure readers can fully understand a model, it would be useful to prepare some sort of glossary to collect and define key terms or key phrases in models.

Compatible edition(s): Enterprise, Professional, Standard, Modeler

  • March 02, 2016
  • Views: 31,800
  • PDF
  • Video

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

  1. Download The True Aqua Distilled Water Company.vpp. You can also find this file at the bottom of this tutorial, under the Resources section.
  2. Open the downloaded project file in Visual Paradigm. You can open a project by selecting Project > Open from the application toolbar.
  3. Open the BPD Distilled Water Ordering Process. Let's identify words or phrases in the diagram to become glossary terms.
  4. 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.
    add cust to glossary
  5. 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.
    Open term
  6. 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.
    Open term editor
  7. 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..
    Entere definition
  8. 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).
    add alias
  9. Enter Buyer in the input window and confirm. Buyer is now an alias of the term Customer.
    alias added
  10. 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.
  11. 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.

    open cust spec
  12. To add a label, click the plus button next to the Label field.
    add label
  13. 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.
    new label
  14. Click OK in the Add Label window. The label is added to the term.
    label added
  15. Click OK in the Term Specification window to return to the glossary grid. You can see the label in the grid, too.
    grid show label
  16. 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.
    open term

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.

  1. 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.
    textual analysis
  2. Let's say the text ordering hotline is worth explaining. Select it. Right-click on the selection and select Add "ordering hotline" to Glossary.
    add to glossary
  3. You can then find the term ordering hotline in glossary grid.
    term added
  4. 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.

  1. Open the glossary grid.
  2. Click the Export to Excel button from the toolbar within the grid window.
    export to excel
  3. In the Export Excel window, specify the output path to save the Excel file in.
    specify output path
  4. Keep the other settings unchanged. Click Export at bottom right.
    excel exported
    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.

Turn every software project into a successful one.

We use cookies to offer you a better experience. By visiting our website, you agree to the use of cookies as described in our Cookie Policy.