Upgrades and Migrations

Before upgrading from an older version of EDG, consult this documentation for migration tasks that might apply to your upgrade. The migration documentation keeps your data and the EDG application functioning correctly after an upgrade; so please pay close attention to those details. You can upgrade from any previous release straight to the current release, but you will need to use the migration documentation starting at the version you are currently on and following along to current release. For example, if you upgrade from version 7.3 to 7.5 you will need to follow the migration notes for 7.3 to 7.4 and 7.4 to 7.5.

Migration Instructions

  • Please back up everything (workspace, database, Tomcat installation, etc.) first.

  • Workspaces cannot be downgraded once upgraded. To revert versions of EDG, use the appropriate backed up workspace.

  • If necessary, take screenshots of the EDG settings on the Rights Management page.

  • Have the credentials and connections strings/URLs handy for Explorer, RDBMS, and S3 connections.

  • Upgrade a test/development environment successfully before upgrading any production environment. This is especially important when the EDG workspace includes UI or model customizations.

7.5 to 7.6 Migrations

  • Turtle files saved in EDG 7.6 no longer contain the # imports and # prefix headers that were present in earlier versions. Files saved with older versions can be opened in EDG 7.6, but on re-saving these headers will be removed.

  • Lucene whitespaceanalyzer is now the default for new installations and will be the default after a restart of EDG. This allows for searching over special characters in Search the EDG.

  • The Permissible Values feature has been redesigned.

    • supports edg:PropertyValueSet and edg:TaxonomyNodeValueSet

    • these no longer require/use edg:graph, instead use any matching value in the available graphs

    • in order to reference permissible values, their graph needs to be owl:imported

    • creating permissible values can now happen from any editor and from workflows, not just the Manage tab

    • make sure that the permissible values schema is owl:imported

    • either navigate to edg:PropertyValueSet or edg:TaxonomyNodeValueSet and create instances using the new button(s)

    • or navigate to a property shape that has the property at its context class and use Modify > Create Property Value Set…

    • or navigate to a concept and use Modify > Create Taxonomy Node Value Set…

    • sample values (max 10) now show up as inferred property, without custom widget

    • to get all values use Explore actions and web services at the value set, or query the inferred property edg:memberValue

7.6 to 7.7 Migrations

ADS Code Generator Bug Fix

If you have developed scripts in ADS, please verify that you did not rely on a bug that we have just fixed: The API code generator was sometimes appending a 2 to the end of a field name. This was the case when the same property was used both in forward and inverse direction at the same class/shape. In that case, for example, ex:hasPart would have been mapped to fields hasPart2 and hasPartInverse. From 7.7 onwards these would be hasPart and hasPartInverse.

7.7 to 7.8 Migrations

  • TopBraid EDG now uses a strict Content Security Policy by default. This disables certain JavaScript features for better protection from XSS attacks. Customizations that use these features must be updated, or else a lax policy can be configured. See Content Security Policy (CSP) for details.

  • ADS graph.withDataGraph and graph.transaction now correctly also change the internal shapes graph that is used by the engine, e.g. to compute sh:values rules. This may theoretically cause slight changes in the semantics of ADS scripts that use graph.withDataGraph or graph.transaction, if these scripts relied on the surrounding shape definitions in the inner callback.

7.8 to 8.0 Migrations

Note

Please contact TopQuadrant Support for detailed migration steps if needed.

Java 17 required

Java must be upgraded to version 17 (OpenJDK or Oracle). Other versions (older or newer) are not supported.

Tomcat 10 required

Tomcat must be upgraded to version 10. Other versions (older or newer) are not supported.

Authentication changes

The authentication system has been redesigned. Migration steps depend on the previous authentication method:

Steps for SAML and OAuth

Authentication must be configured as described in SAML Authentication and Authentication with OAuth 2.0. This involves creating a saml2.yaml and/or oauth.yaml configuration file. Most values can be copied from your previous installation’s context.xml file.

Steps for Form and Basic authentication with users defined in tomcat-users.xml

No action required as of EDG 8.0. However, this option will be removed in a future release, and customers should migrate to the new configuration involving users.yaml, as described in Form Authentication and HTTP Basic Authentication.

Steps for Form and Basic authentication with LDAP integration

This is no longer officially supported. See LDAP Authentication for more information.

New: OpenID Connect (OIDC)

This is available as a new authentication option: Authentication with OpenID Connect (OIDC)

Re-apply Server Configuration and EDG Configuration parameters

Any changes previously made in the Server Administration area under Server Configuration Parameters and EDG Configuration Parameters must be re-aplied. The sections have been renamed to System Configuration and Product Configuration.

These settings were previously stored in a file config.ttl in the Workspace. They are now stored in dedicated asset collections.

Re-enter passwords

Passwords previously entered under Server Configuration Parameters, EDG Configuration Parameters or Password Management must be re-entered.

Migrate SeparateTDB and RDBMS databases

Any EDG workspace configured to use a SeparateTDB or RDBMS database will need to migrate to SharedTDB, or upgrade to Data Platform.

Contact TopQuadrant Support for detailed instructions.

Re-import Workflow Templates

Workflow Templates are now stored in the Platform Governance graph.

  1. Prior to upgrading download your workflow customizations graph

  2. Then RDF file import the file created in step #1 into the Platform Governance graph

Support for owl:SymmetricProperty dropped

Declarations of properties as owl:SymmetricProperty are ignored. Annotate the property shape with dash:symmetric to keep the same effect.

Review URI creation settings

The algorithm that creates URIs from labels now attempts to prevent URIs that cannot be abbreviated to qnames. Use the product configuration setting edgURIsMayNotAbbreviate to retain the old behaviour.

Migrate custom workflows with CommitRules/StatusChangeRules

The long-deprecated workflow actions framework has been deleted. Custom workflows that use the (typcially SWP-based) CommitRules or StatusChangeRules must be migrated to use (typically ADS-based) teamwork:WorkflowStatusScript.

Migrate teamwork:EditRules

Customizations that use (typcially SWP-based) teamwork:EditRules must migrate to (ADS-based) ChangeScript and CommitScripts.

Upgrade Steps for EDG Releases

EDG Upgrade

REQUIRED : TAKE A BACKUP OF THE WORKSPACE (You cannot revert a workspace). Read all the instructions prior to beginning.

  1. Stop Tomcat, make sure the process is fully stopped

  2. Backup and remove the /edg directory and edg.war file located in [Tomcat Root]/webapps/.

  3. Clear Tomcat work and temp directories.

  4. Place the current release’s edg.war found in the download package into the webapps directory

  5. Backup and remove Tomcat lib directory. Extract TopBraid-Auth.zip from current release’s download package into a newly created Tomcat lib directory created from Tomcat distribution. (This step is to update all the SAML and OAuth authentication jars for EDG. Be aware of any jars that are needed in this directory for Tomcat in your distribution.)

  6. Backup and clear the tomcats logs directory (optional)

  7. Start Tomcat (the current war creates a new /edg/ directory)

  8. If your installation used the Interactive setup method, this will need to be redone upon EDG startup. Please refer to backup copy of your previous EDG directory at edg/WEB-INF/setupdata/edg-setup.properties for previous values. Alternatively prior to upgrade, navigate to /edg/tbl/setup in the EDG UI and find these values at the bottom of the page.

  9. Perform migration steps applicable to your installation

  10. Regression test before upgrading production

Note: If your license has expired, you will need to install your new license before upgrading.