Welcome to Semarchy xDM.
This guide contains information about upgrading Semarchy xDM from previous releases.
Preface
Audience
| If you want to learn about MDM or discover Semarchy xDM, you can watch our tutorials. |
| The Semarchy xDM Documentation Library, including the development, administration and installation guides is available online. |
Document Conventions
This document uses the following formatting conventions:
| Convention | Meaning |
|---|---|
boldface |
Boldface type indicates graphical user interface elements associated with an action, or a product specific term or concept. |
italic |
Italic type indicates special emphasis or placeholder variable that you need to provide. |
|
Monospace type indicates code example, text or commands that you enter. |
Other Semarchy Resources
In addition to the product manuals, Semarchy provides other resources available on its web site: http://www.semarchy.com.
Obtaining Help
There are many ways to access the Semarchy Technical Support. You can call or email our global Technical Support Center (support@semarchy.com). For more information, see http://www.semarchy.com.
Feedback
We welcome your comments and suggestions on the quality and usefulness
of this documentation.
If you find any error or have any suggestion for improvement, please
mail support@semarchy.com and indicate the title of the documentation
along with the chapter, section, and page number, if available. Please
let us know if you want a reply.
Overview
Using this guide, you will learn how to plan and perform the upgrade of Semarchy xDM for development and production environments.
Planning the Upgrade
Before the Upgrade
Documentation Review
Before starting the upgrade, you should review the following documents:
-
The Semarchy xDM Release Notes provides the latest information about the Semarchy xDM Release, including new features and bug fixes.
-
The Semarchy xDM Installation Guide provides the procedures for installing and configuring Semarchy xDM. In this guide, you should review the system requirements for this new release.
-
Review the major changes that may impact your upgrade, as well as the required actions listed in Pre-Upgrade Actions. Make sure to review these before starting the upgrade process.
-
Depending on your current version and the upgrade version, some actions may be required after the upgrade process. Review these Post-Upgrade Actions before starting the upgrade process.
Understanding Major, Minor and Patch Versions
Version numbers in Semarchy xDM are expressed in the following
format: <major_version>.<minor_version>.<patch_version>. For example,
version 1.3.2.
The upgrade may be a major upgrade, a minor upgrade or a patch. The differences between the old version number and the new version number define the type of upgrade.
-
A Major Upgrade takes place as soon as the major version differs. Major versions include major feature changes, and typically require repository and data locations upgrade. For example, upgrading from 1.3.2 to 2.0.1 is a major version upgrade.
-
A Minor Upgrade takes place when first digit remains the same but the second differs. Minor versions include minor feature changes, and typically require repository and data locations upgrade. For example, upgrading from 2.0.3 to 2.1.0 is a minor version upgrade.
-
A Patch is applied when the patch version only differs. Patches do not require repository and data location upgrade. For example, upgrading from 2.0.0 to 2.0.3 is patching.
Although the process is the same for all types of upgrade, be aware that the repository and data location upgrade steps may be skipped for patches.
Unless specified otherwise, the upgrade path between two version of Semarchy xDM is direct. You do not need to install intermediate versions.
Select the Upgrade Path
The upgrade supports two paths:
-
In-Place Upgrade consists in installing the new version of Semarchy xDM in place of the previous version and upgrading the existing repositories. With this method, you can revert the environment to its original state by restoring the backup of the application folders and database schemas.
-
Out-of-Place Upgrade consists in replicating the existing Semarchy xDM environment and upgrading the copy. The original environment remains unchanged.
You may choose one of the other path for your infrastructure. This choice depends on your IT infrastructure policies for upgrading.
Upgrade Path Overview
In-Place Upgrade
The upgrade path is as follows:
Pre-Upgrade Actions
Upgrading from version 4.0
There are no breaking changes when upgrading from version 4.0 to this version, and no pre-upgrade action required.
Upgrading from versions 3.x
This version does not support upgrading from versions of Semarchy xDM prior to version 4.0.
Upgrading
This chapter describes the various steps of the upgrade process.
Stop All Application Instances and Connections
Before upgrading, you must stop all applications and user connections to Semarchy xDM. During the upgrade:
-
No application should access the Semarchy xDM services and APIs.
-
No user should access the Semarchy Workbench for design-time or data management operations.
-
No user or application should access the repository or data locations’ database schemas.
You should contact your database administrator and middleware administrator to make sure that the unavailability of Semarchy xDM during the upgrade process is correctly managed.
Stop all Semarchy xDM Applications. This is done either by:
-
Stopping the Semarchy xDM application from your application server administration console.
-
Stopping the application server if it is dedicated to Semarchy xDM only.
Backup Your Installation
Before upgrading, you should make sure that:
-
The schema(s) containing the Semarchy xDM repositories are backed up; Use the Oracle Database utilities for performing such backup operations.
-
The schema(s) containing the Data Locations are backed up; Use the Oracle Database utilities for performing such backup operations.
-
The Semarchy xDM installation folders in the application servers are backed up.
-
Any other relevant content (plug-in Jars, etc.) is also backed up.
| Before going further, make sure that all the required backup are done, and that the entire Semarchy xDM environment is stopped and not accessed by any user or application. |
Duplicate Database Schemas (Out of Place Upgrade)
If you have decided to perform an out-of-place upgrade, you must replicate (Copy) all the schemas (the repositories, data locations, etc) using the Oracle Database utilities.
The new product version, considered as a separate installation, will point to this copy of the schemas.
Use a clear naming convention for these new schemas to be able to identify them easily. For example, if the original schemas are called SEM_REPOSITORY, SEM_DLOC1, etc., the new one may be called SEM_2_2_REPOSITORY, SEM_2_2_DLOC1, etc.
|
Install the New Application Version
Perform the following operation for every application server into which the Semarchy xDM application was deployed.
| When installing a new application version for in-place or out-of-place upgrade, pay attention to the application server and additional libraries versions installed in the current installation. This includes libraries related to security and authentication (role mapper, Waffle, etc.) These libraries are frequently compatible with a certain version of the application server and work with your current configuration. Do not systematically upgrade the application server and those libraries when upgrading the Semarchy application. If you decide to upgrade these libraries and the application server, make sure to review and test the compatibility and configuration. |
Installing for In-Place Upgrade
To install the new application version for in-place upgrade:
-
Deploy the new version Semarchy xDM Web Application Archive file on top of the previous version.
| Refer to your application server documentation for more information about re-deploying applications on top of previous installations. The simple instructions for Apache Tomcat are provided below. |
To perform an in-place upgrade for Apache Tomcat.
-
Backup the
<tomcat>/conf/Catalina/localhost/semarchy.xmlfile. -
Connect to the Apache Tomcat Manager (
http://<tomcat_host>:<tomcat_port>/manager/). -
In the Deploy War File section, click the Select File button and then select the new
semarchy.warfile. -
Click the Deploy button.
-
On the Tomcat server machine, restore the backup of the
semarchy.xmlfile in the<tomcat>/conf/Catalina/localhost/folder.
Installing for Out-of-Place Upgrade
To install the new application version for out-of-place upgrade:
-
Deploy the new version Semarchy xDM Web Application Archive file as a new application, separated from the previous version.
| When performing an out-of-place update, make sure to deploy the new version as a new application. If this new deployment takes place in the application server that already contains the previous version, make sure to change the application name during the deployment. |
| Refer to your application server documentation for more information about deploying new applications. |
Configure the New Application
Perform the following operation for each deployment of the new Semarchy xDM application version.
Configuration for In-Place Upgrade
For in-place upgrade, the updated deployment reuses the configuration already in place. Check this configuration in the application server console or configuration files. The following points should be checked:
-
The datasources for the database schemas are set up and working.
-
The JavaMail Session servers are configured and working.
-
Security is configured.
Configuration for Out-of-Place Upgrade
To configure the new application version in an out-of-place upgrade:
-
Configure new JDBC datasources for the new application deployment only. The datasources include those used to connect the Repository, Data Locations, etc. They should:
-
Point to the copies of the original schemas (e.g.:
SEM_2_2_REPOSITORY,SEM_2_2_DLOC1). -
Be local to the new application. Do not use global datasources
-
Use the same names as the datasources used by the old installation.
-
-
Make sure that the existing JavaMail Session resource is configured or available for the new application.
-
Make sure that the same security environment is configured for the new application.
Datasources should be configured locally for the application. For example, the repository datasource must be called SEMARCHY_REPOSITORY; Declaring this datasource at application-level avoids having multiple Semarchy xDM applications (possibly in different versions) connecting the same repository schema at the same time, which would lead to an erroneous behavior.
|
| By using datasources local to the new application, you make sure that the new application connects exclusively to the copy of the schemas. Similarly, the old version should use local datasources to connect only the original schemas. |
Start One New Application Instance
Perform this operation for a single new application version instance. If you have multiple repositories, you should repeat this operation for each repository.
Start your application server or connect to your application server and start the deployed application.
Upgrade the Repository
| Repository upgrade is required only for major and minor versions. For patches, repository upgrade is not needed and the Repository Upgrade dialog does not appear when you connect. |
| The repository upgrade is an operation that cannot be undone. Make sure you have made a backup of the repository schema before proceeding. |
Before Upgrading the Repository
The Oracle database has introduced in version 11g and 12c a new feature called Automatic Column Group Detection that automatically creates extended statistics for column groups.
These extended statistics prevent the upgrade process to rename certain columns in the repository, causing an ORA-54032: column to be renamed is used in a virtual column expression error to appear during the repository upgrade process.
Before upgrading a repository hosted in an Oracle 11g or 12c instance, it is required to drop these statistics. They will be automatically re-created by the database as needed.
To drop unwanted extended statistics for repositories hosted in Oracle 11g and 12c:
-
Connect to the database hosting the repository schema with a query tool (SQL Developer, SQL*Plus), using the repository schema user.
-
Run the script provided below:
begin
for xrec in (
select
TABLE_NAME, EXTENSION
from
USER_STAT_EXTENSIONS
where
TABLE_NAME like 'MTA%'
and (
EXTENSION like '%FROMEDITION%'
or EXTENSION like '%TOEDITION%'
)
)
loop
DBMS_STATS.DROP_EXTENDED_STATS (
ownname=>null,
tabname=>xrec.table_name,
extension=>TO_CHAR(xrec.extension)
);
end loop;
end;Once the unwanted extended statistics are dropped, proceed with the repository upgrade.
Upgrading the Repository
To upgrade the repository:
-
Connect to the new application instance you have started, using a user account with the semarchyAdmin role. At the first connection, the Repository Upgrade dialog appears.
-
Review the dialog.
-
Click the checkbox and then click the Upgrade button.
The repository upgrade starts. When it completes, the Overview window appears.
| The repository upgrade process can only be triggered by a user with the semarchyAdmin role. |
Upgrade the Data Locations
| Data locations upgrade is required only for major and minor versions. For patches, data location upgrade is not needed, and the Overview page will not show any data location requiring an update. |
| The data location upgrade is an operation that cannot be undone. Make sure you have made a backup of the data location schemas before proceeding. |
| Development data locations upgrade is possible only if the current model edition deployed is valid. Before upgrade a development data location make sure that the deployed model does not raise any design-time validation errors. |
| Development data locations upgrade is possible is the current deployed model corresponds to the latest model state. For such data locations, make sure that the latest version of the model is deployed before performing a data location upgrade. |
Before Upgrading the Data Locations
Before upgrading a data location hosted in an Oracle 11g or 12c instance, it is required to drop the extended statistics that may prevent column renaming. For more information, refer to Before Upgrading the Repository.
| Certain columns are renamed in the data location when upgrading from a version before 3.2.0 to a version after. |
To drop unwanted extended statistics:
-
For each data location:
-
Connect to the database hosting the data location schema with a query tool (SQL Developer, SQL*Plus), using the data location schema user.
-
Run the script provided below:
-
begin
for xrec in (
select
TABLE_NAME, EXTENSION
from
USER_STAT_EXTENSIONS
where (
TABLE_NAME like 'GI_%'
or TABLE_NAME like 'GD_%'
)
and (
EXTENSION like '%B_IS_VALIDATED%'
)
)
loop
DBMS_STATS.DROP_EXTENDED_STATS (
ownname=>null,
tabname=>xrec.table_name,
extension=>TO_CHAR(xrec.extension)
);
end loop;
end;Once the unwanted extended statistics are dropped, proceed with the upgrade.
Upgrading the Data Locations
To upgrade the data locations:
-
Connect to the new application instance you have started, using a user account with the semarchyAdmin role.
-
In Overview page, a warning in the Administration section indicates the list of data locations attached to this repository that require an update.
-
Click the link under this list to perform the upgrade. The Data Location Upgrade dialog appears.
-
Review the dialog.
-
Click the checkbox and then click the Upgrade button.
The upgrade starts. When it completes, the Overview window is refreshed and and warning no longer appears.
| The data location upgrade process can only be triggered by a user with the semarchyAdmin role. |
Restart All Application Instances
The upgrade is now finished.
You can restart all the Semarchy xDM instances in the new version, and open the access through the user interface, services, APIs and database tables.
Post-Upgrade Actions
This chapter describes the actions required after the upgrade process was complete. These actions depend on the current version of Semarchy xDM and the version you upgrade to.
| If no actions is indicated in this chapter for your versions, then no action is required after restarting the Semarchy xDM application instances. |
Upgrading to version 4.1
No Post-upgrade actions are required for users upgrading from a version 4.0 to version 4.1.
Upgrading to version 4.0
Upgrading from a Semarchy xDM version before version 4.0 is not supported.