Does anyone use or create a glossary within a process model to help users who are not in the system all the time with what the objects represent?
Best Reply
Yes, this is quite a standard practice.
We usually create a dedicated folder at the repository level and split it into three subfolders: Terms, Abbreviations, and Standard Terms.
Inside these folders, we keep object definitions of type Technical term:
- Name = the term or abbreviation
- Description/Definition = its explanation or formal definition
One important recommendation is to have some kind of placeholder model in each of these folders where the objects are placed as occurrences. I normally recommend a Matrix model for this purpose. A Spreadsheet model can also be used, but I would not really recommend it — it can be rather unstable, and, more importantly, it cannot be processed properly by scripts if you need this later. Without such a placeholder model, database reorganization may sometimes produce unpleasant surprises.
After that, the same term definitions can simply be reused in your process models. In our projects, we usually connect them on the FAD at the process level, so they can later be reused automatically when generating SOPs or other process documentation.
The Standard Terms folder is especially useful. Many SOPs contain the same recurring definitions — for example, Company, ARIS, and similar terms. Instead of maintaining these separately in every process model, the SOP generation script can simply take the required definitions directly from the Standard Terms folder.
3 Replies
Hello Alexander,
How do you then get the standard terms or objects of the glossary to show on another model? We use the Enterprise BPMN Collaboration Diagram model as our primary model. The desire by the team is to have a 'legend' or glossary on the model that helps the view users understand what the objects are as many of the view users to not have a need to use the system daily like the modelers do.
Any suggestions are appreciated.
You basically have two strategies here.
The first — and the one I would recommend — is shown in the picture. For the process object to which your BPMN model is assigned, you create a Function Allocation Diagram (FAD) and place the relevant glossary terms there as occurrences of the existing glossary objects.
This is also how we usually implement it in our projects. For example, in our SOP generation scripts we define the logic so that, when an SOP is generated for a process, the glossary terms are taken from the FAD assigned to that process.
By the way, this is very similar to your question about risks in the other thread — the same FAD can be used for that purpose as well. And it does not necessarily have to be created at the lowest process level. Depending on how many levels of process decomposition you have, it may make more sense to maintain such information at L2 or L3.
The second strategy — which I would consider a bad practice — is to place the glossary objects directly on the BPMN diagram itself, for example below the pool, so that viewers can see them as a kind of legend.
Technically, this works and I have seen it used. But from a repository management perspective it creates additional problems, because those objects are simply placed on the BPMN diagram without any proper semantic relationship to the process. As the repository grows, this tends to create unnecessary clutter and makes reporting, maintenance and governance more difficult.
So if the goal is not only to visually explain the model, but also to keep the glossary manageable and reusable, I would definitely prefer the FAD approach.
Alexander Cherednichenko on
Yes, this is quite a standard practice.
We usually create a dedicated folder at the repository level and split it into three subfolders: Terms, Abbreviations, and Standard Terms.
Inside these folders, we keep object definitions of type Technical term:
One important recommendation is to have some kind of placeholder model in each of these folders where the objects are placed as occurrences. I normally recommend a Matrix model for this purpose. A Spreadsheet model can also be used, but I would not really recommend it — it can be rather unstable, and, more importantly, it cannot be processed properly by scripts if you need this later. Without such a placeholder model, database reorganization may sometimes produce unpleasant surprises.
After that, the same term definitions can simply be reused in your process models. In our projects, we usually connect them on the FAD at the process level, so they can later be reused automatically when generating SOPs or other process documentation.
The Standard Terms folder is especially useful. Many SOPs contain the same recurring definitions — for example, Company, ARIS, and similar terms. Instead of maintaining these separately in every process model, the SOP generation script can simply take the required definitions directly from the Standard Terms folder.