Overview

Unless otherwise noted, the migration items are cumulative. Thus, beginning with one's current version level, all items from all subsequent sections, i.e., (increasing) version levels, should be checked for possible applicability.

Migration from 5.1.x

Data Migration

TopBraid version 5.2+ has upgraded to RDF 1.1 as well as modified the schema for RDBMS (SDB) for enhanced functionality. Therefore, upgrading to 5.2+ will require administrators to migrate data from any existing TopBraid 5.1 relational database to a new one. A migration utility tool, ‘sdbconvert’, has been created to assist in this process. The tool will invoke a program to connect to your 5.1 database and migrate data into the new relational tables.

Please note:

• The names of the relational tables have changed. TopBraid Version 5.2+ will attempt to connect to the new tables in the database. If they do not exist, it proceeds to see if the old tables exist. If the old tables do not exist in the database the new tables will be created.
• If the old tables exist and the new ones do not, an exception is thrown. The relational database will be unusable until the old tables are dropped or the migration utility has been run.

The following instructions create a new relational database, load existing data into it, create a new workspace, and migrate projects into it. You must reinstall your 5.2+ license file. The commands in italics are examples for reference. Please read this entire document prior to beginning to ensure you understand the migration steps and can apply them to your environment.

1. Shutdown your application:
     bin/shutdown.sh
2. Backup existing database (Ensure this is successful before continuing)
1. Oracle
   http://docs.oracle.com/cd/B28359_01/server.111/b28319/dp_export.htm#g1022624
2. SQL Server
   https://msdn.microsoft.com/en-us/library/ms187510.aspx
3. MySQL
   mysqldump -u username -h hostname -p databaseName > locallySavedDatabase.sql
3. Backup application server file system by copying workspace and webapps to a temporary location and clear temp directories. You cannot use the same workspace for 5.2+.
   1. webapps and workspace:
      mv webapps webapps-51
mv workspace workspace-51
   2. Clear work, temp, and directories from tomcat:
      rm -Rf work/* temp/*
mv logs logs-51
mkdir logs
4. Install 5.2+ war file in tomcat, startup tomcat to deploy the war file.
5. Shutdown tomcat, and copy your existing web.xml to the new web.xml or replace the file.
   If you would like to use a different workspace name for 5.2+, you can edit the web.xml under the init-param commandline –data section to change to another workspace directory. Otherwise, you can use the old name, and it will create a new workspace for you since you already moved the old one to another name in step 4.
6. Download the TQ_51-52_MigrationDocs.zip  from the TopBraid 5.2 Release Notes, and extract this zip file to any directory. Be sure you have connectivity and user update permission to your relational database. From the command prompt, navigate to tq-jena-cmds directory and execute the following command:
   java -jar tq-jena-cmds.jar sdbconvert --jdbc "<jdbc connection string for the database>" --dbUser "<database userid>" --dbPassword "<database password>" --dbType <dbType>
   Where database type can be one of MySQL, Oracle, SQLServer.
7. Copy config.ttl file from the old workspace to the new one so that you don’t have to re-configure the server.
   cp oldworkspace/server.topbraidlive.org/dynamic/config.ttl newworkspace/server.topbraidlive.org/dynamic
8. Create zip files for custom projects and EVNProjects from previous workspace and upload into new workspace.
   1. cd workspace-51
   2. Zip old project: zip ../EVNProjects.zip .project * -r
   3. Repeat for any other custom projects you may have in the old workspace.
   4. Navigate to ‘Server Administration’ in your application. Click “Project Upload” link from that page. You can then upload the zip projects that you had zipped up from the old workspace to this new workspace.
9. Restart tomcat.
   After this restart, you should be able to see all your vocabularies just as before. This concludes your data migration to 5.2+.
10. Existing role management mappings, LDAP, and permission management should be copied from your existing config.ttl. To update or review, see http://www.topquadrant.com/docs/5.1/Installation-and-Administration-Guide_1802517.html for detailed instructions. Note: In 5.2+ you must ensure that “ANY_ROLE” does not belong to “AdministratorGroup”.
11. For questions or issues, please contact support@topquadrant.com.

Changes to the Form Inclusion Mechanism

This may affect users of RDM/EDG and some users of EVN. These users may have to edit or delete customized forms for certain classes.

Background: Up until version 5.1, RDM and EVN included an automated mechanism that created or modified the SWA form layouts of classes if certain vocabularies were included. These vocabularies are

• http://topbraid.org/raci     (RACI properties for instances)
• http://topbraid.org/rdmfact  (RDM Fact properties)
• http://topbraid.org/status   (Status Vocabulary (for codes, concepts, instances, etc.))

When such includes were added, forms were modified to include sections for the new properties. The mechanism based on form manipulation was causing issues and was unnecessary fragile and complex.

As of version 5.2, a different mechanism was implemented that internally uses SHACL definitions to represent form templates. Instead of modifying the forms for each class, a generic mechanism determines dynamically which sections need to be added, regardless of whether the class has a customized form or not.

Migrating to 5.2+: If you have included any of the 3 vocabularies mentioned above, you may see duplicate sections, e.g. two RACI sections, on your forms.  The duplicates are the result of "legacy" form customizations which are now unnecessary. In order to get rid of the duplicate forms, either delete the customized forms or remove the sections that were automatically inserted by the previous mechanism.

AutoClassifier Maui Update

Running the 5.2+ Auto Classifier will require downloading and using the latest version of the Maui server. https://github.com/TopQuadrant/MauiServer/releases

Migration from 5.2.x

LDAP Migration

In 5.3+, TBL LDAP supports multiple configurations, which requires migration of LDAP configurations from TBL 5.2 or earlier. In the following steps, set up the LDAP password immediately as indicated to ensure access to the server (and avoid a shutdown and manual editing of the config.ttl file).

1. In Server Administration > Server Configuration Parameters, copy the LDAP configuration for reference and then remove the configuration LDAP. NOTE: Passwords will also be required for upgrading.
2. Make a backup of TBL.
3. Save a copy of $TOMCAT_HOME/webapps/tbl/WEB-INF/web.xml.
4. Delete $TOMCAT_HOME/webapps/tbl.war.
   1. If Tomcat is running with Hot Deploy enabled, then wait for it to remove the webapps/tbl folder. Otherwise, with Tomcat shut down, manually remove the folder and its contents.
   2. Also, ensure that $TOMCAT_HOME/work/Catalina/[HOSTNAME]/tbl and its contents have been removed.
5. Copy the new edg.war into the $TOMCAT_HOME/webapps/ directory.
6. Let Tomcat recreate the webapps/TBL folder (restarting if necessary).
7. Stop Tomcat, and replace the web.xml file in $TOMCAT_HOME/webapps/tbl/WEB-INF/ by the saved web.xml.
8. Restart Tomcat, and administratively configure the LDAP settings: TBL Administration > Server Configuration Parameters > LDAP Servers (Service Providers)
9. IMPORTANT : Upon saving the LDAP configuration, immediately enter its password and click the SAVE button.

Migration from 5.3.x

Schema Definitions Are Restricted to Ontologies (Configurable)

By default in TopBraid 5.4+, schema definitions for classes, properties, and shapes (constraints) are restricted to ontologies. Other collection types should contain only instances, using include references to ontologies (etc.) as needed. Among other things, this allows performance enhancements for some operations. See Ontology Editor: Classes vs. Instances for more information about this recommended practice.

One change from previous versions, 5.3 and earlier, is that schema-related editing and importing is no longer supported for non-ontologies, i.e., taxonomies, etc. If necessary, EDG Administrators can disable this restriction via the Enable Ontology Optimizations parameter; see Server Configuration Parameters > Advanced Parameters for details.

Organizations, Users, and Emails

In TopBraid 5.4+, introduces new  Organizational Structure  components as part of a new  Governance Model , which provides enterprise contexts for other asset collections. This changes some organization, user, and email implementations from TopBraid versions 5.3 and earlier. The organizational context provides hierarchical groupings of users according to job titles. This allows users to be associated to various governance roles indirectly and abstractly via their job titles.

Users and emails

A new Users page shows role assignments. For installations based on Tomcat-provided authentications (i.e., non-LDAP), email addresses for notifications can be set in the users page. Users not conveyed through one of the Tomcat authentications options (Tomcat-users or LDAP) can no longer receive notifications.

Keywords

In TopBraid 5.4+, associating keywords to a collection (as in TopBraid 5.3 and earlier), has been replaced by assigning a collection to one or more "goverance areas", either business or data-subject areas. To assign a subject area, simply create the collection for that area in the Governance Area page or edit the metadata for the collection. See Governance Model Overview: Governance Areas for details. To filter collections, use the Find Asset Collection page.

Search Results

Search results from the editor screens have been limited to 1000 entries by default to improve initial load times. When viewing larger collections, filter the results to narrow down under 1000. The number of results returned can be configured through the administrative section by updating the parameter 'maximum number of table rows'. 

Search the EDG (TopBraid EDG only)

Search the EDG is now backed by a Lucene index. This change will greatly improve performance over large or many collections. With the index, partial matching is not supported. See Lucene integration for more details.

Migration from 5.4.x

URL Loading from Remote Graphs

In TBL 5.4 and earlier, if an imported URI was not found in the workspace, then TBL would default to loading it from the web. This default loading behavior could be disabled via administration parameter: Server Configuration Parameters > Advanced Parameters > Disable URL graph loading. Now, in 5.5+, remote loading is disabled by default to avoid accessing unvetted data. The parameter for URL loading is no longer configurable through administrative views, but if it must be enabled, an administrator can add (or modify):  cfg:enableWebImports "true"^^xsd:boolean ; in TBL's config.ttl file (located within the workspace's server.topbraidlive.org project).

Graphs that previously relied on the default loading behavior can generate errors on non-local includes (i.e., owl:import), which can be seen in the Server Administration > TBL Log. To address this, provide local copies of the referents, transitively, as needed.

Server Configuration Parameters: ui link base and Server URL

The 5.4 Server Configuration Parameter ui link base has been removed (its 5.4 documentation is here). Use the Server URL parameter instead. Installations that had a setting for ui link base should ensure that on that same configuration page, the Server URL parameter (doc here) is set correctly. Installations using email notifications should verify that web links in notification emails still work correctly after migration. If not, the Server URL setting should be double-checked.

Installations that have Server URL left at the previous default of http://localhost:8083/tbl, for TopBraid Composer, must either delete or replace this setting, leaving it either empty or with the correct URL-base for the TBL server.

SHACL-based SKOS

In TBL 5.5+, SKOS forms have moved to a SHACL basis, which means that taxonomies and (possibly) ontologies might need to update their imports as follows.

• Anything using SKOS-XL should import SKOS-XL Shapes.
• Anything using SKOS forms should verify that they are now importing SKOS Shapes.

A failure to import SKOS-XL Shapes now means that users will see a SKOS form, not a SKOS-XL form, even if SKOS-XL data exists. Hence, it will look like the SKOS-XL relationships have disappeared.

Migration from 5.5.x

Data Platform

The Data Platform client-side database is moving to <workspace>/_Data/db-cache.tdb (from <workspace>/Cache/db-cache.tdb)

EDG

Job Titles in the Governance Framework:

Phase-out of Job Titles: The EDG Governance Model allows the creation of an organizational structure, and the assignment of users and security roles to the organizational hierarchy. In previous versions, it was necessary to create Job Titles for each organization. Users and security roles were then assigned to those Job Titles. This indirect assignment through Job Titles has proven to be cumbersome and to add little value. Starting with EDG 6.0, Job Titles will be phased out.

In 6.0, there is a setting “Enable Job Titles” in the EDG Configuration. It is off by default, and should be left off for new deployments. In this mode, Job Titles are disabled, and users and security roles are assigned directly to organizations.

If you already have created Job Titles in the Governance Model, you must set this setting to true. In this mode, EDG 6.0 will behave the same as the previous version with regards to Job Titles.

We expect to remove support for Job Titles completely in a future release. Therefore, if you currently use job titles, please contact TopQuadrant support to discuss migration options.

Viewers cannot create working copies:

In some previous versions, permission to create new working copies/workflows was affected by a configuration option: Viewers cannot create working copies. This option has been removed.

If the option was OFF (the default), EDG 6.0.0 will behave the same as before.

If the option was ON, then the following needs to be considered:

• Any users or security roles that are directly assigned as Viewers on the Users tab of an asset collection will now be able to create working copies/workflows. This is a change in EDG 6.0.0.
• Users or security roles that have a governance role on the asset collection will now be able to create working copies/workflows. This is a change in EDG 6.0.0. However, this ability can now be disabled for selected governance roles, under: Server Administration > Setup > EDG Configuration Parameters > Governance Roles.

An asset collection is in at most one governance area

Asset collections can no longer be assigned to multiple governance areas. Any collection with multiple areas should delete its area associations, leaving at most one (see collection utilities: Settings > Metadata > subject area).

Manage utilities > SPIN Constraint Libraries and See Customized Forms

From 6.0, these features have been disabled, and users are encouraged to migrate to SHACL. If required, these features can be reactivated locally (contact customer support), but keep in mind that they will be removed in a future release.

Migration of Development Customizations

Ontologies

Ontologies no longer import SPIN by default, neither does the standard teamworkconstraints. If your ontologies have relied on the latter owl:imports (transitively), you need to add the SPIN Standard Library (SPL) to your includes by hand. (cf. Developer Guide: Creating and maintaining new SPIN constraint libraries - DEPRECATED))

Forms

The non-SHACL approach for customizing form layouts is now deprecated and will be removed in a future release. Please use SHACL constraints to customize form layouts. See the Developer Guide: Customizing Form Layouts.

Teamwork project type

• Any custom teamwork:ProjectType should be extended with a teamwork:isReadOnlyTypeFunction triple similar to the value of the original project type that they were cloned from.
• The teamwork:projectHeaderBar extension point for teamwork:ProjectType has been removed. Contact TopBraid Support for migration advice.

Tabs

Beginning in 6.0, there is a new mechanism for adding custom tabs to asset collection views.

• This change affects any 5.x customizations that use teamwork:ProjectTab or teamwork:TagTab. These need to be modified as described in the DeveloperGuide: Adding New Tabs for Asset Collections.
• Customizations using the swa:TabsActivationScript element or the swa.initTabs JavaScript function might need updating. To retain the SWA-specific styling, add class="swa-tabs" to the tab container. Otherwise, the tabs will use the jQuery UI tabs style. Furthermore, the active tab is no longer remembered between page reloads, and is no longer reflected as a #fragment in the URL.