Installation Guide

Introduction

This guide describes the installation process of migration-center.

Migration-center has 3 main components:

  • Database component

  • Client component

  • Jobserver component

Depending on which adapter you are using there might be additional components. Refer to the adapters specific user guide for details.

Prerequisites

To install the migration-center Database component, the installer requires either one of the following to be able to connect to the database:

  • a 32-bit Oracle Client where the database installer is running, configured to connect to the database

  • a 32-bit Oracle Database if the installer is run on the database server directly

If the installer is run with a 32-bit Oracle Client the Oracle Database software can be either 32-bit or 64-bit

For the migration-center Client component to be able to connect to the Oracle Database after it is installed the same requirements as the database installer, mentioned above, need to be met.

Installing migration-center

Each migration-center component has its own installer and the kit has a main installer that assists the installation of each component.

The three individual components can also be distributed and installed with separate assistant, as shown in the following table:

Main installation assistant

setup.exe

migration-center Client

MigClient/MigClientSetup.exe

migration-center database

Database/InstallDataBase.exe

migration-center Server Components (Job Server)

ServerComponents/SPsetup.exe

The installation is started with setupMigCenter.exe, which is found in the root directory of the installation kit.

The installation can be aborted before the component selection step by pressing the [cancel] button.

By pressing [Back], the user can navigate to the previous pages in order to change or edit options.

The migration-center installation package should not be placed in a folder/path containing special characters like “( ) ;” as this can interfere with the installation process.

Main Installer

At the following step, the user will choose the components of migration-center to install.

The following are different installation variants:

  • Full installation All components of migration-center are installed

  • Compact Installation This variant installs the migration-center Client and database only.

  • Custom installation The user-defined installation allows the user to select specific components.

The full installation is recommended as a first installation option, or a custom installation can be performed by selecting only components that need to be installed.

Although the components can be installed individually, for full functionality at least one instance of each component must be deployed and the components must be able to connect to one another.

By confirming the choice by selecting [Next], all chosen components will be installed one after another. For each of the components there will be an individual installation assistant.

Client

The Client installer might need to be run with Administrative rights in order to set some windows compatibility settings. If these are not set the Object Types section of the client might cause issues.

Select destination location

To install the Client, select the installation path for the application. The default installation path proposed by the installer is recommended but can be changed if needed.

Select start menu folder options

During the installation shortcuts in the Windows Start Menu will be created for migration-center. The name of the folder for these shortcuts can be set here.

You also have the option of not creating a Start Menu folder by clicking on the checkbox.

Select shortcut placing options

During the installation shortcuts to the Desktop or to the Quick Launch Bar can be created.

Installation summary

Before starting the installation process, all previously set options are displayed. In order to change settings, the user can navigate to the previous pages by clicking [Back]. By clicking [Install], the installation is started.

Database

This database installer prepares the database for use with migration-center by creating a user, tables, installing the packages containing migration-center functionality and setting default configuration options. All of these objects will be created in a schema called FMEMC. Currently it is not possible to change the schema’s name or install multiple schemas on the same database instance.

The database installer requires a 32-bit 11g/12c/18c/19c Oracle Client or Instant Client to connect to the Oracle server. See information in the Prerequisites section.

Database connection

First the connection details to the database must be entered. The database user must be the predefined SYS user or an Oracle administrative user with enough privileges. And the database name must be selected from the dropdown field.

Creating the FMEMC user manually and using it for installing the database is possible. Refer to the Advanced Installation section below for more details.

You can test the credentials with the selected database by selecting the Test Connection button. A message box will confirm if the connection is established or not.

If the connection is successful, proceeding to the next screen allows entering the license key.

Selecting the tablespaces path

At this point, the path (on the Oracle server) for the tablespaces of the database is set. The default path provided by the selected database instance is recommended.

If setting a different path, make the folder exists on the Oracle server.

Also, the location for the database installation log file MigrationCenter.log can be set is set.

The migration-center database schema will be installed by clicking [Install].

The progress bar in the lower area of the screen informs the user about the progress of the database installation steps.

The log file records several database actions run by the setup routine. Therefore, this log data file is very useful for support in case problems occur during the installation, such as error messages due to insufficient privileges. The location for the log file should therefore be chosen carefully.

Selecting Listener port and date/time pattern

The next screen allows you to set the Oracle Listener Port. This has to match the listener port configured on the Oracle Listener. Default is 1521.

You can also set the Datetime Pattern that will be used for displaying date values in the Client. The dropdown menu includes of 4 the mostly widely used date/time formats.

If the migration-center database schema was successfully installed, the [Finish] button appears, clicking the [Finish] button closes the installer.

Database objects created during migration-center database schema installation:

During the installation, the following Oracle Users will be created for migration-center.

User

Authorizations

FMEMC

This Oracle User is the owner of all migration-center objects and tablespaces

Default password is migration123. Password can be changed after authorization.

GRANT CONNECT TO FMEMC

GRANT RESOURCE TO FMEMC

GRANT CREATE JOB TO FMEMC

GRANT SELECT ON SYS.V_$INSTANCE TO FMEMC

GRANT SELECT ON SYS.DBA_DATA_FILES TO FMEMC

GRANT SELECT ON SYS.DBA_TABLESPACES TO FMEMC

GRANT CREATE VIEW TO FMEMC

Additionally the user FMEMC will be granted to use the following Oracle packages:

  • SYS.UTL_TCP TO FMEMC;

  • SYS.UTL_SMTP TO FMEMC;

  • SYS.DBMS_LOCK TO FMEMC;

  • SYS.UTL_RAW TO FMEMC;

  • SYS.UTL_ENCODE TO FMEMC;

  • SYS.DBMS_SCHEDULER TO FMEMC;

  • SYS.DBMS_OBFUSCATION_TOOLKIT TO FMEMC;

Furthermore, during the installation, the following tablespaces will be created for migration-center:

  • FMEMC_DATA (40MB)

  • FMEMC_INDEX (20MB)

These tablespaces are set to expand in steps of 10MBs according to the usage and needs of migration-center.

The user role FMEMC_USER_ROLE will be created and granted the required privileges on FMEMC schema objects. This role must be granted to any database user that needs to use migration center.

Database advanced installation

The tablespaces and FMEMC user can be created manually via scripts, and the Database installer can be run with the FMEMC user afterwards, instead of using the SYS user. This can be done by running the scripts located in ...\Database\Util folder of the installation kit. The scripts are:

  • create_tablespaces_default_location.sql or create_tablespaces_custom_location.sql

  • create_user_fmemc.sql

These tablespaces must be created prior to the creation of the FMEMC user.

The tablespaces can be separated or merged into any number of individual datafiles, but the tablespace’s names cannot be changed (FMEMC_DATA and FMEMC_INDEX must not be changed).

This option is useful for if the default settings for the user FMEMC and tablespaces do not meet the requirements of the customer or conflict with internal company policies and guidelines.

Server Components

Windows installation

The migration-center Server Components, or Jobserver, is the part which contains all the adapters that connect to the source and target systems. The installation process will copy the files and also create a windows service.

Before starting the installation you need to set the JAVA_HOME (if using JDK) or JRE_HOME (if using JRE) environment variables.

Select destination location

Next, the user will select the installation location for the Server Components. The default installation path proposed by the installer is recommended but can be changed if needed.

Select Job Server port

Next you can select the port on which the migration-center Client will communicate with the Jobserver. The default port is 9700 but any free port can be used.

Select log folder location

Default value is the logs folder in the Server Components installation folder, but it can be set to any valid local path or UNC network share. Write access to the log location is needed by the user which under which the Jobserver will be running.

Since version 3.14 the log location is only set for the adapter logs. The server logs location is manually set in the mc-core/logback.xml file, using the FOLDER_LOG property.

Completion of the installation

Complete the installation by selecting Install.

Linux Installation

Not all adapters are available on the Linux version of Server Components. The ones available are:

  • Scanners: Documentum, Filesystem, Database, eRoom, Exchange

  • Importers: Documentum, Filesystem, InfoArchive

The Linux version of the migration-center Server Components can be found in the folder ServerComponents_Linux.

In order to install the Migration Center Job Server extract the archive Jobserver.tar.gz in the desired location using the command:

tar -zxvf Jobserver.tar.gz

All necessary Job Server files will be extracted in the “Jobserver” folder.

To install the Job Server as a service / daemon, follow these steps:

1. Switch to the “bin” folder of the “Jobserver” folder

2. Run the command sudo ./installDaemon.sh

Run the installDaemon.sh as a user that has administrative permissions (sudo).

Instead of installing the Job Server as a service/daemon, you can run it in the terminal by executing the script ./runConsole.sh in the bin folder

The default TCP listening port is 9701 and can be changed in “server-config.properties” file located in “lib/mc-core” folder.

For running Documentum Scanner or Importer on Linux the DFC (Documentum Foundation Classes) needs to be configured in “conf/dfc.conf” as it is described in the Scanner and Importer user guides.

Multiple Jobserver installations

Depending on the requirements or possibilities of each migration project, it can make sense to install multiple Job Servers across the environment, either to share the workload, or to exploit performance advantages due to the geographical location of the various source and/or target system, i.e. installing the Job Server on a node as close as possible to the source or target system it is supposed to communicate with.

In terms of throughput, local installations will provide benefits over remote installations and local networks will always be faster than remote networks.

Besides throughput, latency needs to be considered as well, since increased latency can affect performance just as much, even leading to timeouts or connection breakdowns in severe cases.

Starting migration-center components

Jobserver

After the installation is complete, the Jobserver needs to be started before it can be used.

Windows

You can start or stop the service using the scripts in the Jobserver folder:

  • startService.bat for starting the service

  • stopService.bat for stopping the service

Or by opening the Windows Services window, selecting the Migration Center Job Server service and starting it.

Alternatively the server can be started in console mode using the runConsole.bat script.

Linux

The Linux Job Server can be started or stopped by running equivalent Linux scripts inside the “Jobserver/bin” folder

  • ./startDaemon.sh for starting the daemon

  • ./stopDaemon.sh for stopping the daemon

Instead of installing the Job Server as a service/daemon, you can run it in the terminal by executing the script ./runConsole.sh in the bin folder.

Client

During installation of the Client, a desktop icon (optional) and a Start Menu entry were created. By default this can be found in Start-> (All) Programs-> fme AG-> migration-center Server Components <Version>. The migration-center Client can be started by using the shortcuts from these locations.

After the Client starts you can connect to your migration-center Database using the default credentials:

User: fmemc Password: migration123

Uninstalling migration-center

This section describes how to uninstall the individual components of migration-center.

Uninstalling the Client

The migration-center Client can be uninstalled by running the unins000.exe uninstall wizard located in the Client installation folder. It can also be uninstalled by using „Add or Remove Programs“ or “Programs and Features” item in the Control Panel (depending on the version of Windows used). You can find the Client listed under the name „migration-center Client <Version>“, it can be uninstalled by selecting the entry and clicking [Remove].

Uninstall links are also provided in the Start Menu program group created during installation. By default, this is Start-> (All) Programs-> fme AG-> migration-center Client <Version>.

Uninstalling the Database Schema

Uninstalling the migration-center database schema will delete all data within that schema. It is no longer possible to recover the information after that. Please back up the database schema before uninstalling it.

An uninstall script is provided with the migration-center installation package. The drop_fmemc_schema.sql script can be found in database/util. Run this script against the Oracle database instance using the SYS user. The FMEMC schema should be removed using the Oracle administration tool of your choice.

Make sure no connections with the user FMEMC exist, otherwise the script will fail to execute properly. Should this happen, the script can be re-run after closing all connections of the user.

Uninstalling the Jobserver

Windows

The migration-center Server Components can be uninstalled by running the unins000.exe uninstall wizard located in the Jobserver installation folder. It can also be uninstalled by using “Add or Remove Programs” or “Program and Features” item in the Control Panel (depending on the version of Windows used). You can find the Server Components listed under the name “migration-center Server Components <Version>” and can be uninstalled by selecting the entry and clicking [Remove].

Uninstall links are also provided in the Start Menu program group created during installation. By default, this is Start-> (All) Programs-> fme AG-> migration-center Server Components <Version>.

The SharePoint adapters have an additional CSOM service which can be installed as an extra step not mentioned in this user guide. Please uninstall any CSOM services you might have before uninstalling the Jobserver

Linux

To uninstall the Job Server as a service/daemon, follow these steps:

  • Go to the “bin” folder inside “Jobserver” folder

  • Run the command ./uninstallDaemon.sh

Run uninstallDaemon.sh as a user that has administrative permissions (sudo).

Backup and Restore

Since in migration-center all the critical data and configuration is saved in the database, only backing up the migration-center database schema is needed.

Backup a migration-center database

Before starting the backup process ensure that there are no scanners, importers, transformation / validation jobs and no scheduled jobs running

To back up a database used by migration-center it is sufficient to back up only the data within the FMEMC schema. The easiest way to do this is with Oracle’s EXP. See screen shot below for the basic steps required to back up a schema. For more information consult the documentation provided by Oracle.

Starting with Oracle 11g release 2, the empty table might not be exported at all. This happens when the database parameter DEFERRED_SEGMENT_CREATION is set to TRUE. Initially this parameter is set to TRUE. To force exporting all tables from the FMEMC schema the following commands should be run connected as user FMEMC: ALTER TABLE SCHEDULER_RUNS ALLOCATE EXTENT; ALTER TABLE SCHEDULERS ALLOCATE EXTENT;

Restoring a migration-center database

To restore the backup, follow the steps below:

  1. If the database instance where the backup should be restored does not contain the FMEMC user, please create it first as it this describe in the Installation Guide.

  2. Use Oracle’s “imp” utility for importing the dump file previously created by the “exp” utility. See screen shot below for the basic steps required to restore a database schema from a dump file. For more information consult the documentation provided by Oracle.

Note: The same character sets in the Oracle Client should be used when exporting and importing the data.

Upgrading migration-center

Upgrading an older installation of migration-center usually consists the following steps:

  1. Uninstall existing Client and Jobserver installations

  2. Install the new version of Client and Jobserver from the new installation package

  3. Upgrade the migration-center Database by running the Database installer against the existing instance

In this section we will cover only the Database upgrade. Instructions on uninstalling and installing the Client and Jobserver components can be found in the previous sections of this user guide.

Considerations before upgrading

Before starting the upgrade process it is always advised to backup the existing data as it is described in the previous chapter.

The migration-center database installer supports upgrading migration center databases starting with version 3.0.

Prerequisites for upgrading from version 3.0.x to the latest version

The following conditions need to be fulfilled for the upgrade procedure to work (these are checked by the installer):

  • The old database’s version must be one of the following: 3.0.x, 3.0.1.985, 3.1.0.1517, 3.1.0.1549, 3.1.1.1732, 3.1.2.1894, 3.2.0.2378, 3.2.1.2512, 3.2.2.2584, 3.2.2.2688, 3.2.3.2808, 3.2.4.3124, 3.2.4.3187, 3.2.4.3214, 3.2.4.3355, 3.2.5.3609, 3.2.5.3768, 3.2.6.3899, 3.2.6.4131, 3.2.7.4348, 3.2.7.7701, 3.2.7.7831, 3.2.7.7919, 3.2.8.7977, 3.2.8.8184, 3.2.8.8235, 3.2.8.8315, 3.2.9.8452, 3.3.8573, 3.4.8700, 3.5.8952, 3.5.8952, 3.6.8970, 3.7.1219, 3.8.0125, 3.9.0513, 3.9.0606, 3.9.0614, 3.9.0606, 3.9.0704, 3.10.0823, 3.10.0905, 3.11.1002, 3.12.1219, 3.12.0226, 3.13.0403, 3.13.0416, 3.13.0508, 3.14.0630, 3.14.0807, 3.15.0930, 3.15.1023, 3.15.1218, 3.16.0331, 3.17.0630, 3.17.0810

  • Any running jobs (scanners, importers, schedulers, transformations, validations) must be finished or stopped

You can check your current database version in the Client’s “About” window. If your version is not one of the above please contact our technical support at support@migration-center.com.

Considerations regarding updating database version older than 3.1.0.x

  • Due to the new update feature released with migration-center 3.1.0, a new instance of an existing scanner may detect updates for objects scanned with previous versions even though the objects haven’t changed from the previous scan. This behavior always applies to virtual documents or documents that have dm_relations and occurs due to the information used by the new features in migration-center 3.1 not being available in the previous release. For this reason, a new scan will recreate this information on its first run.

  • Transformation rules created with a version older than 3.1.0 which use the system attribute r_folder_path might need to be reconfigured. This is because migration-center 3.1 now stores absolute folder paths instead of paths relative to “scanFolderPaths” as was the case with the previous versions.

  • Database upgrade from previous versions older than 3.1.2: as a result of the upgrade process increasing the default size for attribute fields to 4000 bytes (up from the previous 2000 bytes), Oracle’s internal data alignment structures may fragment. This can result in a performance drop of up to 20% when working with updated data (apparent when transforming / validating / resetting). A clean installation is not affected, neither is new data which is added to an updated database, because in these cases the new data will be properly aligned to the new 4000 byte sized fields as it is added to the database.

  • If the database contains Virtual Documents and objects that are part of scanned Dctm Relations (this does not apply to FileSystem adapter) some additional checks are done by installer. In case any of these checks fail an error is raised by the installer. In this case stop the installation and contact our technical support at support@migration-center.com.

Considerations regarding updating database version 3.1.2

Due to changes and new functionalities implemented in migration-center version 3.2 that rely on additional information not present in older releases, the following points should be considered when updating a database to version 3.2 or later:

  • The concatenate function will only have 5 parameters for newly added transformation rules. Reason: the “Concatenate” transformation function has been extended to 5 parameters for version 3.2. Transformation rules using the “Concatenate” function and created with a previous version of migration-center will retain their original 3 parameters only.

  • The system rule “mc_content_location”, which allows the user to define or override the location where the objects’ content files are stored will be available for use only in migration sets created after the database has been upgraded to version 3.2 Reason: the “mc_content_location” system rule is new to migration-center version 3.2 and did not exist in previous versions

  • The Filesystem scanner won’t create the “dctm_obj_link” attribute anymore Reason: with version 3.2 of migration-center scanners and importers are no longer paired together. The “dctm_obj_link” attribute was created automatically by the Filesystem scanner in previous iterations because it was a Filesystem-Documentum adapter. Since this no longer applies to the current Filesystem scanner which is just a generic scanner for filesystem objects and has no connection to any specific target system, it won’t create any attributes specific to particular target systems either. If objects scanned with a Filesystem scanner are intended to be migrated to a Documentum system, the “dctm_obj_link” rule must be created and populated with transformation rules in the same way as any other user-defined rule.

  • The Filesystem scanner won’t detect changes in a file’s metadata during subsequent scans for files which have been scanned prior to updating to version 3.2 Reason: detecting changes in a file’s external metadata (in addition to the file’s content) is a new feature of the Filesystem scanner in migration-center 3.2; previous versions of migration-center did not store the information which would be required by the current Filesystem scanner to detect such changes. A change to a file’s modification date would trigger the update mechanism though and would also enable full 3.2 functionality on subsequent scans.

Upgrading the Database component

A previous version of the migration-center database can be upgraded to the current version. The installer will detect supported database versions eligible for the upgrade and offer to upgrade the database structure, migration data and stored procedures to the current version.

To start the process simply start the Database installer of the new version of migration-center.

Enter the credentials for connecting to the old migration-center database. If the detected version of the database component is supported for upgrade, the following screen will appear:

Reminder that backing up your database before proceeding with the upgrade is highly advised

Enter a location for saving the database installation/upgrade log file. In case of any errors this log file will be requested by our technical support staff.

After clicking “Next” the appropriate database scripts will be executed.

An upgrade can take in excess of 1 hour to perform, depending on the amount of data and database system performance. This is normal and does not mean the installer has stopped responding. Please do not try to close the installer application or otherwise intervene in the process.

After the upgrade finishes you should see the Progress bar filled and the Finish button.

Congratulations you have successfully upgraded your migration-center database to the latest version! :)

Last updated