Document toolboxDocument toolbox

Migration Guide: Enterprise Glossary 2022.1

Owned by Nils Meyer
Last updated: Apr 12, 2023
14 min read

Purpose of this page

This page describes the neccesary steps to update your Enterprise Glossary to Version 2022.1. Some changes in this version make it necessary to check the compatibility of the database before updating. You might need to make some adjustments to the content of your Glossary in order to update to the new version. This page provides and describes the checks on your database and makes suggestions for actions that can be taken to pass any failed check. If possible, alternative measures are presented and their advantages and disadvantages are explained.

Our goal with version 2022.1

With version 2022.1 the focus will be on depicting the SAP content in a clearer and more cohesive way. We want to achieve this by creating customizable Entities for each synchronized SAP Object in the Glossary. These new Entities come in two kinds of flavors; SAP Entities for your synchronized SAP Objects, and Custom Entities are for all your other needs to create Entities without a primary SAP reference. All synchronized information for any synchronized SAP Object will be available in one SAP Entity. This Entity and its underlying Template can be customized and you can add any manual information to the SAP Entity. This makes choosing a Technical Equivalent for your Glossary Entity obsolete. Also there is no longer a separate, technical view on SAP Objects, only one view with all the desired and customized information about the correspondig SAP Object remains. All requirements for this update are essentially aimed at establishing a distinct relation between SAP Objects and their respective Entity in the Enterprise Glossary.

How to update

Please make sure that your Enterprise Glossary has version 2020.1 or newer.

If your Installation has the version 2020.0 or older, please perform an update to 2021.3.8 first:

https://bluetelligence.atlassian.net/wiki/spaces/EGUM213/pages/3163095865

Setup Downloads:
Enterprsie Glossary 2021.3.8
Synchronization Service 2021.3.8

.NET Core 6 is required on the mashine that runs the IIS:

https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-6.0.11-windows-hosting-bundle-installer

  1. Freeze work on your Enterprise Glossary for the time being

  2. Create a backup of your database if you dont have one already

  3. Execute our script on your database with SQL Server Management Studio (see next section of this page)

  4. Check the results of the script

  5. If required make adjustments to your Enterprise Glossary to meet the requirements

  6. Perform checks again untill all checks are passed

  7. Perform an update as usual, following our guide:

Update Guide for 2020.1 and newer

https://bluetelligence.atlassian.net/wiki/spaces/EGUM213/pages/3163095686

Setup Downloads:
Enterprise Glossary 2022.2.2
Synchronization Service 2022.2.2

Requirements for the update

Check your database compatability with this SQL Script

Here you can see and copy a SQL script that checks your database for the requirements of this update. Simply execute the following script in SQL Server Management Studio on your Enterprise Glossary database:

-- Migration checks -- 1) Check if there is only one Template per SAP category type SELECT templates.TemplateId, templates.SapObjectType, templates.Type, templates.TemplateName FROM (SELECT tpl.Id AS TemplateId, tplc.SapObjectType, tplc.Type, COUNT(*) OVER (PARTITION BY tplc.SapObjectType,tplc.Type) AS duplicates, tplv.Name AS TemplateName FROM TEMPLATE tpl JOIN TemplateVersion tplv ON tpl.Id=tplv.TemplateId JOIN TemplateCategory tplc ON tplc.TemplateVersionId = tplv.Id WHERE tpl.ConnectedObjectTypeId IS NULL AND tpl.IsDeleted=0 AND tplc.SapObjectType IS NOT NULL AND tplc.Type>0 AND tplv.VersionNumber = (SELECT top 1 tv.VersionNumber FROM TemplateVersion tv WHERE tv.TemplateId=tplv.TemplateId ORDER BY tv.VersionNumber DESC) GROUP BY tpl.Id, tplc.SapObjectType, tplc.Type, tplv.Name) as templates WHERE templates.duplicates>1 --2) Check if all SAP categories in a template are of the same type SELECT templates.TemplateId, templates.TemplateName FROM (SELECT tpl.Id AS TemplateId, tplc.SapObjectType, tplc.Type, COUNT(*) OVER (PARTITION BY tpl.Id) AS duplicates, tplv.Name AS TemplateName FROM TEMPLATE tpl JOIN TemplateVersion tplv ON tpl.Id=tplv.TemplateId JOIN TemplateCategory tplc ON tplc.TemplateVersionId = tplv.Id WHERE tpl.ConnectedObjectTypeId IS NULL AND tpl.IsDeleted=0 AND tplc.SapObjectType IS NOT NULL AND tplc.Type>0 AND tplv.VersionNumber = (SELECT top 1 tv.VersionNumber FROM TemplateVersion tv WHERE tv.TemplateId=tplv.TemplateId ORDER BY tv.VersionNumber DESC) GROUP BY tpl.Id, tplc.SapObjectType, tplc.Type, tplv.Name) as templates WHERE templates.duplicates>1 -- 3) Checks if a SAP object is used in multiple categories of multiple entities SELECT categories.Id, categories.Name as EntityName, categories.CategoryObjectId as CategorySapObjectId FROM ( SELECT entity.Id, ev.Name, etc.ConnectedObjectId as CategoryObjectId, COUNT(*) OVER (PARTITION BY etc.ConnectedObjectId) AS qty FROM Entity entity join EntityVersion ev on ev.EntityId = entity.Id join EntityVersion_TemplateCategory_ConnectedObject etc on etc.EntityVersionId = ev.Id where entity.IsDeleted=0 and etc.ConnectedObjectId is not null and ev.VersionNumber = ( select top 1 entityVersion.VersionNumber from EntityVersion entityVersion where entityVersion.EntityId=ev.EntityId order by entityVersion.VersionNumber desc) group by entity.Id, ev.Name, etc.ConnectedObjectId ) categories WHERE categories.qty > 1 ORDER BY categories.name, categories.Id -- 4) Check if the SAP object matches across all categories SELECT categories.Id, categories.Name as EntityName, categories.CategoryObjectId as CategorySapObjectId FROM ( SELECT entity.Id, ev.Name, etc.ConnectedObjectId as CategoryObjectId, COUNT(*) OVER (PARTITION BY entity.Id) AS qty FROM Entity entity join EntityVersion ev on ev.EntityId = entity.Id join EntityVersion_TemplateCategory_ConnectedObject etc on etc.EntityVersionId = ev.Id where entity.IsDeleted=0 and etc.ConnectedObjectId is not null and ev.VersionNumber = ( select top 1 entityVersion.VersionNumber from EntityVersion entityVersion where entityVersion.EntityId=ev.EntityId order by entityVersion.VersionNumber desc) group by entity.Id, ev.Name, etc.ConnectedObjectId ) categories WHERE categories.qty > 1 ORDER BY categories.name, categories.Id -- 5) Check if the Technical equivalent matches the object in SAP categories SELECT entity.Id AS EntityId, ev.Name, ev.ConnectedObjectId AS TechnicalEquivalent, etc.ConnectedObjectId AS CategoryObject FROM Entity entity JOIN EntityVersion ev ON ev.EntityId = entity.Id JOIN EntityVersion_TemplateCategory_ConnectedObject etc ON etc.EntityVersionId = ev.Id WHERE entity.IsDeleted=0 AND ev.ConnectedObjectId IS NOT NULL AND etc.ConnectedObjectId != ev.ConnectedObjectId AND ev.VersionNumber = (SELECT top 1 entityVersion.VersionNumber FROM EntityVersion entityVersion WHERE entityVersion.EntityId=ev.EntityId ORDER BY entityVersion.VersionNumber DESC) -- 6) Check for entities with Technical equivalent, but without a SAP category SELECT entity.Id, ev.Name FROM Entity entity JOIN EntityVersion ev ON ev.EntityId = entity.Id join TemplateVersion tplv on tplv.Id = ev.TemplateVersionId WHERE entity.IsDeleted=0 AND ev.ConnectedObjectId IS NOT NULL AND ev.VersionNumber = (SELECT top 1 entityVersion.VersionNumber FROM EntityVersion entityVersion WHERE entityVersion.EntityId=ev.EntityId ORDER BY entityVersion.VersionNumber DESC) and 0 = (select Count(*) from TemplateCategory WHERE TemplateVersionId = tplv.Id and SapObjectType IS NOT NULL) -- 7) Check for SAP objects selected in an entity category but also set as Technical equivalent in another entity SELECT entity.Id AS EntityId, ev.Name, etc.ConnectedObjectId as CategoryObjectId FROM Entity entity JOIN EntityVersion ev ON ev.EntityId = entity.Id JOIN EntityVersion_TemplateCategory_ConnectedObject etc on etc.EntityVersionId = ev.Id WHERE entity.IsDeleted=0 AND ev.VersionNumber = (SELECT top 1 entityVersion.VersionNumber FROM EntityVersion entityVersion WHERE entityVersion.EntityId=ev.EntityId ORDER BY entityVersion.VersionNumber DESC) AND etc.ConnectedObjectId in (SELECT etc.ConnectedObjectId FROM Entity otherEntity JOIN EntityVersion otherEv ON otherEv.EntityId = otherEntity.Id WHERE otherEntity.IsDeleted=0 AND otherEv.ConnectedObjectId = etc.ConnectedObjectId AND otherEntity.Id!=entity.Id AND otherEv.VersionNumber = (SELECT top 1 ev1.VersionNumber FROM EntityVersion ev1 WHERE ev1.EntityId=otherEv.EntityId ORDER BY ev1.VersionNumber DESC)) ORDER BY ev.Name -- 8) Check for Entities that have a TechnicalEquivalent set, but were not published yet(they have only a Draft) SELECT entity.Id as EntityId, vers.Name as EntityName FROM Entity entity JOIN EntityDraft draft ON draft.EntityId = entity.Id JOIN EntityVersion vers ON vers.EntityId = entity.Id WHERE vers.ConnectedObjectId IS NOT NULL AND entity.IsDeleted=0 AND entity.Id not in (SELECT e.Id FROM Entity e JOIN EntityVersion ev ON ev.EntityId = e.Id WHERE ev.EntityDraftId IS NULL)

 


Requirements Overview

  1. Only 1 Template per SAP Object Type

  2. All SAP Categories in a Template are of the same type

  3. SAP Objects are used in the SAP Categories of not more than 1 Entity

  4. The same SAP Object is used across all categories of an Entity

  5. The Technical Equivalent and the SAP Object in SAP Categories match

  6. All Entities with Technical Equivalent have at least one SAP Category

  7. SAP Objects selected as Technical Equivalents are not used in SAP Categories of another Entity

  8. Entities with an Technical Equivalent must not be unpublished


1. Only 1 Template per SAP Object Type

Before you can migarte your database to the new version, each SAP Object Type may only be used by one Template. Meaning that a SAP Category of a certain type may only be used by one Template.

How to read the results of the check

The results of the script list all Templates, where a SAP Object Type is used by more than one Template. So the results will be either at least two Templates or empty. When this check does not return any results, the check is passed.

 

TemplateId (TemplateId)

SapObjectType
(SapObjectType)

Type
(ConnectionType)

TemplateName
(TemplateName)

 

TemplateId (TemplateId)

SapObjectType
(SapObjectType)

Type
(ConnectionType)

TemplateName
(TemplateName)

1

27

1

3

AFO-Template

2

46

1

3

AFO_Template_new

3

32

4

2

Query-Template

5

41

4

2

Query_Template_new

In the Example above, two Templates for Analysis for Office, and two Templates for Queries were found. The column “TemplateName” lists the name of the Templates for you, to identify the conflicting Templates.

How to meet the requirement

In this case, the optimal aproach to meet the requirement depends on the purpose and utilization of the affected Templates. As a result, only one Template of a certain SAP Object Type may remain. Conflicting Templates need to be deleted to pass this check.

  • Templates are not utilized → Option 1

  • Templates are only utilized by irrelevant Entities → Option 1

  • Templates are utilized by relevant Entities → Option 2 (only few Entities need migration) or Option 3 (many Entities need migration)

Option 1: Deleting the Entities: You can delete all but one Template per SAP Object Type. In order to delete a Template, all Entities that are based on a Template must be deleted first.

Option 2: Changing the Template in the Entities: You can change the used Template by editing the affected Entities, so that only one Template of a SAP Object Type is used. Afterwards the unused Templates can be deletd, leaving only one Template per SAP Object Type.

Option 3: Marking unwanted Templates as deleted: With a SQL command, all but one Template with a certain SAP Object Type can be marked as deleted, without deleting or editing the Entities. The Entities will no longer be accessible through the application, but can be merged on database level, after the update with a custom script.

update Template set IsDeleted=1 where Id=TEMPLATE_ID

← Back to the Overview



2. All SAP Categories in a Template are of the same type

The migration of your Templates can only be performed, when all SAP Categories of one Template, are of the same type. Meaning that one Template should not have two or more SAP Categories of different types, even when those types are not used by another Template.

How to read the results of the check

The results of the script list all Templates, that use more than one type of SAP Category. Each Template is listed once for each SAP categroy type that is used by the Template. Templates are listed with ID and Name. When this check does not return any results, the check is passed.

 

TemplateId
(TemplateId)

TemplateName
(TemplateName)

 

TemplateId
(TemplateId)

TemplateName
(TemplateName)

1

21

Query-InfoProvider-Template

2

21

Query-InfoProvider-Template

3

52

Mixed-Template

4

52

Mixed-Template

5

52

Mixed-Template

In the Example above, two different Templates that use more than one type of SAP Category were found. The first Template, “Query-InfoProvider-Template“, uses two different types of SAP Categories, the second, “Mixed-Template“, uses three different types.

How to meet the requirement

Decide which Template should be used for which SAP Object Type. Remove all differing SAP Categories from all affected Templates and take requirement 1 into account while doing so.

← Back to the Overview



3. SAP Objects are used in the SAP Categories of not more than 1 Entity

The migration of your Entities can only be performed, when there is no SAP Object that is used in the SAP Categories of more than one Entity. Meaning that a SAP Object needs to be used exclusively by an Entity or not be used by any Entity at all.

How to read the results of the check

The results of the script list all instances, where a SAP Object is used in SAP Categories of multiple Entities. The results are grouped by the SAP Object used. This is displayed in the “CategorySapObjectId” column. The other columns shot the ID and Name of the Entities that use the SAP Object. When this check does not return any results, the check is passed.

 

Id
(EntityId)

EntityName
(EntityName)

CategorySapObjectId
(CategorySapObjectId)

 

Id
(EntityId)

EntityName
(EntityName)

CategorySapObjectId
(CategorySapObjectId)

1

1243

Revenue

43343

2

4321

Net Income

43343

3

2123

Actual Cost

67767

4

2321

Cost of Production and Delivery

67767

5

1321

Total Cost

67767

In the Example above, two SAP Objects are used in the SAP Categories of multiple Entities. The first SAP Object is used by two different Entities, “Revenue“ and “Net Income“. The second SAP Object is used by three different Entities, “Actual Cost“, “Cost of Production and Delivery“ and “Total Cost“.

How to meet the requirement

Identify the reason, why the SAP Object is used in multiple Entities. When it was done by mistake, consolidate, commit to one Entity and remove the remaining Entities. You can also just remove the SAP Object from the categories in the Entities that should not be representaive for the SAP Object. This way the remaining, maunal information will be migrated into Custom Entries and thereby preserved.

← Back to the Overview



4. The same SAP Object is used across all categories of an Entity

The migration of your Entities can only be performed, when all SAP Categories across one Entity have the same SAP Object applied. Meaning that different SAP Objects of the same type in one Entity will prevent a successful migration.

How to read the results of the check

The results of the script list all Entities with different SAP Objects in their categories. Entities are listed with their ID and Name. Entities are listed for each SAP Object that they use, see the “CategorySapObjectId” column. When this check does not return any results, the check is passed.

 

Id
(EntityId)

EntityName
(EntityName)

CategorySapObjectId
(CategorySapObjectId)

 

Id
(EntityId)

EntityName
(EntityName)

CategorySapObjectId
(CategorySapObjectId)

1

200

Product

43343

2

200

Product

32211

3

355

Customer

98672

4

355

Customer

78352

5

355

Customer

71190

In the Example above, the Entity “Product” uses two different SAP Objects in its SAP Categories. The Entity “Customer“ uses three different SAP Objects.

How to meet the requirement

Identify the reason, why there are multiple SAP Objects used in the affected Entities. If it was done by mistake, select the correct SAP Object in the affected Categories and make sure that the same SAP Object is used across all categories of each Entity. When it was done intentionally, you can use the feature “Linked Entities” to create a manaul relation between Entities. Either way, the conflicting SAP Objects must be adjusted in the affected categories.

← Back to the Overview



5. The Technical Equivalent and the SAP Object in SAP Categories match

The migration of your Entities can only be performed, when the Technical Equivalent matches the SAP Object that is applied to the SAP Categories of the same Entity. The Technical Equivalent is not mandatory though and can also be left blanc. A mismatch between the techncial equivalent and the SAP Object that is used in the categories is not allowed.

How to read the results of the check

The results of the script list all Entities that have a certain SAP Object set as Technical Equivalent, but a different SAP Object in any of its categories. The affected Entities are listed with their names. For each deviating Object in the categories, a record is listed with the Technical Equivalent and category object. When this check does not return any results, the check is passed.

 

EntityId
(EntityId)

Name
(EntityName)

Technical Equivalent
(TechnicalEquivalent)

CategoryObject
(CategorySapObjectId)

 

EntityId
(EntityId)

Name
(EntityName)

Technical Equivalent
(TechnicalEquivalent)

CategoryObject
(CategorySapObjectId)

1

1303

Cost of Sales

197639

973637

2

1304

Cost of Sales

197639

839373

3

870

Sales Report

715984

902201

In the Example above, the Entity “Cost of Sales” has two SAP Categories with different SAP Objects assigned. Both SAP Objects differ from the SAP Object that is set as Technical Equivalent. The Entity “Sales Report“ has one Category with a differing SAP Object.

How to meet the requirement

Identify the reason, why the Technical Equivalent and the SAP Objects in the categories do not match. If it was done by mistake, you should correct this and make sure, that the SAP Object matches across the entire Entity, in the Technical Equivalent (when one is set) and all SAP Categories. When you want to create a manual relation to a different SAP Object, then you can use the “Linked Entities” function.

← Back to the Overview

6. All Entities with Technical Equivalent have at least one SAP Category

The migration of your Entities with the Techncial Equivalent set can only be performed, when the Template that is used for those Entities, has at least one SAP category. This is necessary to ensure, that there is only one Template per SAP Object Type and no conflicts within any SAP Templates occur.

How to read the results of the check

The results of the script list all Entities that have a SAP Object set as Technical Equivalent, but there is no SAP Category in the Template that is used by the Entity. The Entities are listed by their ID and Name. When this check does not return any results, the check is passed.

 

EntityId
(EntityId)

Name
(EntityName)

 

EntityId
(EntityId)

Name
(EntityName)

1

1101

PU Canada

2

1102

FI Canada

3

1103

DS Canada

4

1104

QA Canada

In the Example above, four different Entities have a Technical Equivalent set, but they all use a Template that has no SAP Categories.

How to meet the requirement

You can either remove the Technical Equivalent from the affected Entities, or you can add a corresponding SAP category to each of the affected Templates. Keep in mind, that only one Template per SAP Object Type is allowed.

← Back to the Overview

7. SAP Objects selected as Technical Equivalents are not used in SAP Categories of another Entity

The migration of your Entities can only be performed, when the SAP Objects, that are used as Technical Equivalents, are not used in any SAP Category of any other Entity but the one where the SAP Objects are set as Technical Equivalent.

How to read the results of the check

The results of the script list all Entities that have a SAP Object set as Technical Equivalent, but the same SAP Object is also used in a SAP Category by another Entity. The Entities are listed by their ID and Name together with the ID of the SAP Object in the affected SAP Category. Duplicate records mean, that the Object is in multiple SAP Categories of the same Entity. When this check does not return any results, the check is passed.

 

EntityId
(EntityId)

Name
(EntityName)

CategoryObjectId
(CategorySapObjectId)

 

EntityId
(EntityId)

Name
(EntityName)

CategoryObjectId
(CategorySapObjectId)

1

3906

PU Canada

498074

2

3906

PU Canada

498074

3

2715

DS Canada

384746

In the Example above, the Entity “PU Canada“ uses a SAP Object that is used as Technical Equivalent in a different Entity. The Entity “DS Canada“ uses a SAP Object in one Category that is also used as Technical Equivalent elsewehere.

How to meet the requirement

You have to decide for the affected SAP Objects, which of the Entities should become the representative Entries after the update; either the Entity with the Techncial Equivalent or the Entity with the SAP Object in the SAP Categories.

When you want to keep the Entity with the Techncial Equivalent, then you have to apply the same SAP Object to all SAP Categories in the Entity with the Techncial Equivalent. You also have to remove the SAP Object from the SAP Categories of all Entities that are listed by the script.

When you want to keep any other Entity, then you have to remove the Technical Equivalent and all usage of that SAP Object in all SAP Categories of the remaining Entities.

← Back to the Overview

8. Entities with a Technical Equivalent must not be unpublished

The migration of your Entities can only be performed, when Entities with a Technical Equivalent have at least one published version.

How to read the results of the check

The results of the script list all Entities that have a Technical Equivalent, but do not have a published version. When this check does not return any results, the check is passed.

 

EntityId
(EntityId)

Name
(EntityName)

 

EntityId
(EntityId)

Name
(EntityName)

1

258

Material

2

336

Plant

In the Example above, the Entities “Material“ and “Plant“ have a Technical Equivalent set, but there is only an unpublished draft version present.

How to meet the requirement

You can either delete or publish the draft version of each listed Entity in order to meet the requirement of this check.

← Back to the Overview

After the Update

Load License with first start

With the first start after the update, you will need to load a new version of your license XML file. We will provide that file to you before hand.

Authorization

When the update has been performed, you should check and adjust your authorizations. Unlike before, the access to SAP Entities can now be restricted via Roles. Please have a look at the manual and take neccesary steps if needed: https://bltg-um.scrollhelp.site/eg-um/v2022.1/manage-roles

SAP Synchronization

After the update you should execute synchronization jobs for all connected SAP systems to ensure that all SAP objects are in a proper state.

SAP Templates

Check the layout of all SAP Templates. The Where-Used Field is now on its own tab and might need some adjustment to be visually pleasing.

Custom Entities

All former Entities that had no SAP objects applied to their categories before the update will be converted to Custom Entities. Any needed manual information that is actually related to a SAP Entity should be transferred to the corresponding SAP Entity. The affected Custom Entities can be deleted afterwards.

Clear Cache

To make sure that there is no interferance with old data from the browser cache, clients should clear the cache of their browser when visiting the updated page.

© 2023 bluetelligence GmbH. All rights reserved.
No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of bluetelligence GmbH. The information contained herein may be changed without prior notice. bluetelligence and Enterprise Glossary and their respective logos are trademarks or registered trademarks of bluetelligence GmbH. SAP, ABAP, BAPI, SAP NetWeaver, SAP BI, SAP BW, SAC, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany or an SAP affiliate company. All other product and service names mentioned are the trademarks of their respective companies.
Impressum – Legal Notice: https://bluetelligence.de/en/imprint
Privacy policy: https://www.enterprise-glossary.de/datenschutz.php
Atlassian privacy policy: https://www.atlassian.com/legal/privacy-policy