Welcome to Stambia MDM.
This guide contains information about upgrading Stambia MDM from previous releases.

Preface

Audience

This document is intended for administrators interested in upgrading the Stambia MDM platform from previous versions.

If you want to learn about MDM or discover Stambia MDM, you can watch our tutorials.
The Stambia MDM 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

Monospace type indicates code example, text or commands that you enter.

Other Stambia Resources

In addition to the product manuals, Stambia provides other resources available on its web site: http://www.stambia.com.

Obtaining Help

There are many ways to access the Stambia Technical Support. You can call or email our global Technical Support Center (support@stambia.com). For more information, see http://www.stambia.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@stambia.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 Stambia MDM for development and production environments.

Planning the Upgrade

Before the Upgrade

Documentation Review

Before starting the upgrade, you should review the following documents:

  • The Stambia MDM Release Notes provides the latest information about the Stambia MDM Release, including new features and bug fixes.

  • The Stambia MDM Installation Guide provides the procedures for installing and configuring Stambia MDM. In this guide, you should review the system requirements for this new release.

  • 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 Stambia MDM 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 Stambia MDM 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 Stambia MDM 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 Stambia MDM 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:

  1. Stop All Application Instances and Connections

  2. Backup Your Installation

  3. Install the New Application Version

  4. Configure the New Application

  5. Start One New Application Instance

  6. Upgrade the Repository

  7. Upgrade the Data Locations

  8. Upgrade the Pulse Metrics Warehouse

  9. Restart All Application Instances

  10. Perform the Post-Upgrade Actions

Out-of-Place Upgrade

The upgrade path is as follows:

  1. Stop All Application Instances and Connections

  2. Backup Your Installation

  3. Duplicate your Repository, Data Location and Pulse Metrics Warehouse

  4. Install the New Application Version

  5. Configure the New Application

  6. Start One New Application Instance

  7. Upgrade the Repository

  8. Upgrade the Data Locations

  9. Upgrade the Pulse Metrics Warehouse

  10. Restart All Application Instances

  11. Perform the Post-Upgrade Actions

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 Stambia MDM. During the upgrade:

  • No SOA-enabled application should access the Stambia MDM Web Services.

  • No user should access the Stambia MDM 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 Stambia MDM during the upgrade process is correctly managed.

Stop all Stambia MDM Applications. This is done either by:

  • Stopping the Stambia MDM application from your application server administration console.

  • Stopping the application server if it is dedicated to Stambia MDM only.

Backup Your Installation

Before upgrading, you should make sure that:

  • The schema(s) containing the Stambia MDM 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 schema(s) containing the Pulse Metrics Warehouse (If you use that option) are backed up; Use the Oracle Database utilities for performing such backup operations.

  • The Stambia MDM 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 Stambia MDM environment is stopped and not accessed by any user or application.

Duplicate Repositories, Data Locations and Pulse Metrics Warehouse (Out of Place Upgrade)

If you have decided to perform an out-of-place upgrade, you must replicate (Copy) the schemas containing the repositories, data locations and Pulse Metrics Warehouse 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 Stambia MDM application was deployed.

Installing for In-Place Upgrade

To install the new application version for in-place upgrade:

  1. Deploy the new version Stambia MDM 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.

  1. Backup the <tomcat>/conf/Catalina/localhost/stambiamdm.xml file.

  2. Connect to the Apache Tomcat Manager (http://<tomcat_host>:<tomcat_port>/manager/).

  3. In the Deploy War File section, click the Select File button and then select the new stambiamdm.war file.

  4. Click the Deploy button.

  5. On the Tomcat server machine, restore the backup of the stambiamdm.xml file in the <tomcat>/conf/Catalina/localhost/ folder.

Installing for Out-of-Place Upgrade

To install the new application version for out-of-place upgrade:

  1. Deploy the new version Stambia MDM 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 Stambia MDM 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 Repository, Data Location and Pulse Metrics Warehouse 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:

  1. Configure new JDBC datasources for the new application deployment only. The datasources include those used to connect the Repositories, Data Locations and Pulse Metrics Warehouse schemas. They should:

    • Point to the copies of the repositories, data locations and Pulse Metrics Warehouse (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.

  2. Make sure that the existing JavaMail Session resource is configured or available for the new application.

  3. 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 Stambia MDM 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 that you have made a backup of the repository schema before proceeding.

To upgrade the repository:

  1. Connect to the new application instance that you have started, using a user account with the semarchyAdmin role. At the first connection, the Repository Upgrade dialog appears.

  2. Review the dialog.

  3. 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 that 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.

To upgrade the data locations:

  1. Connect to the new application instance that you have started, using a user account with the semarchyAdmin role.

  2. In Overview page, a warning in the Administration section indicates the list of data locations attached to this repository that require an update.

  3. Click the link under this list to perform the upgrade. The Data Location Upgrade dialog appears.

  4. Review the dialog.

  5. 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.

Upgrade the Pulse Metrics Warehouse

Pulse upgrade is required only for major and minor versions. For patches, Pulse upgrade is not needed, and the Overview page will not show that the Pulse Metrics Warehouse requires an update.
The Pulse Metrics Warehouse upgrade is an operation that cannot be undone. Make sure that you have made a backup of the schemas before proceeding.

To upgrade the Pulse Metrics Warehouse:

  1. Connect to the new application instance that you have started, using a user account with the semarchyAdmin role.

  2. In Overview page, a warning in the Administration section indicates that the Pulse Metrics Warehouse attached to this repository requires an update.

  3. Click the link under the warning to perform the upgrade.

The upgrade starts. When it completes, the Overview window is refreshed and and warning no longer appears.

The Pulse Metrics Warehouse 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 Stambia MDM instances in the new version, and open the access through the user interface, web services 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 Stambia MDM 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 Stambia MDM application instances.

Upgrading to version 3.2

Stambia MDM 3.2 introduces changes that require the post-upgrade actions listed below.

Matching Process

In versions prior to 3.2, a matcher includes a single matching condition.
Starting with version 3.2, a matcher is composed of several matching rules and supports scoring for automated merge and confirmation. To reflect this new matcher and provide performance enhancements, the data certification job was re-designed and the data location structures have been modified.

Matching Rule Upgrade

When a model is upgraded, existing matchers are converted to the new matchers in order to deliver the same matching behaviour:

  • The existing matcher for each entity is converted to a matcher with a single matching rule called Default, with a matching score of 100. This rule contains the old matcher’s binning expressions and matching condition.

  • The Merge Policy is configured with all the thresholds set to 0, so that all duplicate groups detected automatically merge.

  • The Auto-Confirm Policy is configured as follows:

    • Auto-confirm golden records threshold is set to 100. Merged duplicate groups are never automatically confirmed.

    • Auto-confirm singletons is checked. Singletons are automatically confirmed.

Recommended Action
After the upgrade, model designers should review their matchers to benefit from the new capabilities and enable automated merge and confirmation for the business users and data stewards.

Data Location Upgrade

When a data location is upgraded, the data structures are modified to support the the new matching rules, scoring, suggested merges and auto-confirmation. See the Table Structures section in the Stambia MDM Integration Guide for more information about these tables.

Recommended Action
Customers consuming golden and master records from GD and MD tables and using duplicate management-related columns should review the new structures and propagate changes in their data integration flows.

Data Administrators should gather statistics on the data location schemas to make sure that subsequent processing use statistics updated with the updated structure and values.

In addition, the existing records are upgraded with the following rules:

  • Golden records keep their existing IDs and confirmed/validated state.

  • Confirmed or unconfirmed golden records keep their status.

  • Partially confirmed golden records are upgraded to Not Confirmed.

  • The existing duplicate management workflows remain, but the duplicates listed in these workflows disapear.

  • In the lastest data edition:

    • Golden records split and confirmed by the user are upgraded in an exclusion group.

    • A confidence score is automatically computed.

  • In previous data editions:

    • The exclusion groups are not computed.

    • The confidence score is set to null for singletons and to 100 for non-singleton golden records.

Recommended Action
Administrators and data stewards should review the upgrade rules listed above and should test the upgrade prior to applying it on their production environment. After the upgrade, data stewards should review the confirmation state of the duplicates and execute duplicate management workflows to confirm duplicates as needed.

Customized Search Forms

In versions prior to 3.2, all the default built-in search methods (full text, advanced, by form and SemQL) were available in the business object views.
Starting with 3.2, it is possible to create customized forms and define which of the search methods or customized forms are available in applications.

Recommended Action
After the upgrade, model designers should review and customize the search methods available in their applications.

PL/SQL Functions

Starting with version 3.2, it is possible to declare user-defined PL/SQL functions. By declaring these functions, designers make them available in the SemQL editor and avoid SemQL warnings raised by these functions.

Recommended Action
After the upgrade, model designers should declare all PL/SQL functions used in their SemQL clauses. By doing so, model validation will no longer raise warning for these functions.

ID Generation in Web Service

Starting with version 3.2, web services now return the IDs of records as they are created and expose the capability to automatically generate ID for records pushed into loads. New web service operations let you provision series of IDs.

Recommended Action
Integration teams using web services should review their integration flows. Flow using web services with round trips (persist row then read) to retrieve IDs should be simplified using the new ID generation capabilities.

Upgrading from versions prior to 3.1

Review the post-upgrade actions listed below if upgrade from a version prior to version 3.1.

Model Privilege Grants for SemarchyAdmin

In versions prior to 3.1, the semarchyAdmin role had a hardcoded full access to the data on all models.
Starting with version 3.1 the privilege grant for this role is no longer hardcoded, and can be modified.

When a creating a new model or upgrading an model, a model-level privilege grant is automatically created for the semarchyAdmin role with Grant full access to the model selected to keep the same level of privileges.

Recommended Action
After the upgrade, model designers may want to modifying this privilege grant to reduce the privileges of the semarchyAdmin role on the data, and prevent platform administrators from accessing data in the hub.

Model Privileges Grants for the Integration Web Services

In versions prior to 3.1, accessing the integration web services required a role having platform-level read/write privileges on the data location.
Starting with version 3.1, a specific option called Grant access to integration web services appears in the model privilege grants to define whether a role can access this model’s data via web services.

When upgrading, roles that could access the integration web services thanks to their privileges on the data locations will automatically have this option checked for the models deployed in the data location.

Recommended Action
After the upgrade, model designers may want to review and modifying this privilege grant to prevent access to the integration web services to certain roles.

Pulse Metrics

Starting with version 3.1, Pulse Metrics collection process is scheduled and managed by the Execution Engine. The Stambia MDM Pulse Metrics Executable (metrics.bat or metrics.sh command) is now obsolete.

Required Action
After the upgrade, administrators should stop all scheduled executions of the Pulse Metrics Executable, and configure the Pulse Metrics schedule in the workbench. Refer to the Configuring Pulse Metrics section in the Stambia MDM Administration Guide for more details.

Browser Support

Stambia MDM 3.1 discontinues the support for old web browsers. The updated list of supported web browser is available in the Client Requirements section of Stambia MDM Installation Guide.

Recommended Action
Administrators should inform all Stambia MDM users of the new client requirements.

Upgrading from versions prior to 3.0

Review the post-upgrade actions listed below if upgrade from a version prior to version 3.0.

Applications

Default Application

The built-in Default Application (No Application) that existed in previous releases - and could not be modified or deleted - disappears in v3.0. When the upgrade takes place, an application named Default Application is created as a replacement. This application provides the same features, but can be modified or deleted.

Recommended Action
If you do not need a Default Application and wish to enable user access only via your applications, remove this application after the upgrade.

Securing Applications

This version introduces the capability to configure application features (Entities List, Dashboards, Lineage, etc.), and allow access to the selected features depending on roles.

Recommended Action
Review the configuration for each of your applications, un-select features to hide them and/or set roles for features access.

Attribute Groups

Attribute groups are no longer supported starting with Stambia MDM 3.0. The default forms generated when displaying entities in applications now organize attributes as User Attributes and Built-in Attributes

Recommended Action
Create forms and table view, business objects and business object views to display entities content to replace attribute groups.

Form Views

Views Upgrade

This version introduces a new computed Attribute Type field for the form attributes. This field if computed for all forms the first time you open a form view.

Required Action
After the upgrade, open any form view in the model. An Upgrade Views message prompt appears. Click OK to start the upgrade. At the end of this process, the form view editor opens. Press CTRL+S to finish the update of all the views.
This process takes place once. You should not be again prompted for upgrading the views.

Primary Key and Source ID

In form views, it is no longer required to explicitly choose a key attribute among the Golden ID, Primary key or Source ID. If you add the entity’s Primary Key attribute to a form, the form will automatically display the key that is the most appropriate for the context (master record, golden record, source record, etc.) and the type of entity (fuzzy or exact matching).

For example:

  • For a source record of a fuzzy matching entity, the Source ID will be displayed.

  • For a golden record of a fuzzy matching entity, the Golden ID will be displayed.

Recommended Action
Review the form views that include key attributes, and replace these key attributes by the entity Primary Key.
In form views created for the purpose of data entry, replace also the Source ID with the entity Primary Key. This second point is important as the Source ID only recognized as a simple text field.
If you want to use the display component specific to IDs, replace the Source ID by the Primary Key.

Only use a specific key only if you want to explicitly display this key in a context: For example, to display the Golden Record ID when viewing a master record.

Layout

Form views no longer support multi-column layout for forms and sections. When the upgrade takes place:

  • The section order and attribute order in the section are preserved.

  • The columns layout for forms and sections is not preserved.

The result are forms with a Flow Layout. The Grid Layout enable you to configure sections and attributes at absolute positions on a grid, offering the superior features than a multi-column layout.

Recommended Action
After the upgrade, review all the form views. For those of the forms requiring a specific layout, configure them with a Grid Layout and reposition the sections and attributes to restore the form appearance.

Business Object Views

Business object views now support defining form views for browsing data and for data entry. As a consequence, certain business object views pairs (one used for the sole purpose of data entry - marked as non-visible -, plus one used for navigating) can be merged into single business object views.

Recommended Action
Review the business object views and consider merging data-entry-only business object views with their navigation counterparts.

User Preferences

The upgrade process preserves user-defined filters, but resets the columns selection and user-defined sort in the data tables to the default values:

  • All the columns available in the table views are made visible for the users.

  • If a customized sort is defined in the model, this sort is used. Otherwise, records are not sorted.

Recommended Action
Application users should review the column displayed as well as the record sort and reapply their preferences.