Installation Guide

Introduction

This guide describes the installation process of migration-center.

Migration-center has 3 main components:

  • Database component

  • WebClient component

  • Jobserver component

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

Prerequisites

To run the migration-center Database and WebClient installers you need Java 8 or 11 installed and either the JAVA_HOME or JRE_HOME environment variables set.

Note that the JAVA_HOME and JRE_HOME variables should point to the root install folder of JDK or JRE and should not contain the \bin folder in the path.

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 separately with the installers from the following table:

Main installation assistant

setupMigCenter.exe

migration-center WebClient

WebClient/McWebClientSetup.exe

migration-center Database

Database/InstallDataBase.bat

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.

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

Web Client

The WebClient installer deploys an Apache Tomcat server containing the migration-center WebClient component.

Java environment

The installer will check and display the path for the JAVA_HOME or JRE_HOME environment variable. This needs to be a valid 64-bit Java 8 or Java 11 installation.

Note that the JAVA_HOME and JRE_HOME variables should point to the root install folder of JDK or JRE and should not contain the \bin folder in the path.

Click Next to proceed.

Select destination location

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

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

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. Click Install to start the installation.

Install in progress

Wait for the install to finish.

Finish the installation

You have the option of launching the migration-center WebClient after clicking on Finish.

This will open your default browser with the localhost URL for accessing the WebClient https://localhost/mc-web-client

Certificate configuration

Additional configuration might be needed for installing own security certificate.

See the following section in the WebClient User Guide for more details: Configure HTTPS Certificates

Database

The Database installer is started by running the InstallDataBase.bat file or by running the InstallDataBase.jar file directly. Both these require a valid Java installation.

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

Welcome screen

The first screen containing some general information. Click Next to proceed.

Connection Details

Insert the details for connecting to the database instance where you want to install the migration-center FMEMC schema. Set username, password. The user must be the predefined SYS user or an Oracle administrative user with enough privileges. Then set the database details host, port and service name.

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 details by clicking Test Connection. Click on Next to proceed.

Selecting the logs and tablespaces path

Set the location to create the log files for the database installer.

Set the location for the database tablespaces. The default path provided by the database instance is recommended.

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.

Enter License Key

Insert a valid migration-center license key.

Wait for the install to finish

When the installation finishes click on Next to proceed.

Set date/time pattern

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

Click Finish to complete the installation.

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.

Database AWS RDS installation

To install the migration-center database component in an Oracle instance on AWS RDS you must use the scripts provided in the ...\Database\Util\AWS-RDS folder under the install kit. Follow the steps in this order:

  1. run the create_tablespaces_aws_rds.sql script

  2. run the create_user_fmemc_aws_rds.sql script

  3. run the Database installer and use the FMEMC user to connect to your AWS RDS Oracle instance

Server Components

Windows installation

The migration-center Server Components, or Jobserver, is the part which contains all the connectors that interact with 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 connector 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 connectors 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.

Accessing Network Shares

For the migration-center Jobserver to access network shares successfully, you need to configure which user is used for this. This is needed when using a network share in the parameter of any connector (i.e. exportLocation) or when working with objects that have the content saved on a network share.

There are two main ways of configuring this:

Using local user account

This method consists of configuring the Jobserver service to run with the local user account that you are are currently logged into your Windows session. Afterwards create the entry in the Credential Manager to the network share you wish to access.

Open the properties of the migration-center Job Server service and access the Log On tab. Select This account and enter the details of the user you are currently logged on to:

Then either try to access the network share in Windows Explorer and make sure to check Remember my credentials checkbox after entering the account details:

Or access the Credentials Manager directly and create a new entry for the network share with the account that has access to it.

Using domain account

This method consists of configuring the Jobserver service to run with a Active Directory / Domain user and configuring the network share with access for that user directly:

Mapped network drives are not visible to applications running as a Windows Service. Therefore avoid using them with migration-center.

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.

WebClient

Open the WebClient URL address in the browser: https://<server-name>/mc-web-client/login

After the page loads, click on Manage connections and create a new database connection with all the needed details.

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 WebClient

The migration-center WebClient can be uninstalled by running the unins000.exe uninstall wizard located in the WebClient 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 WebClient listed under the name „migration-center WebClient <Version>“, it can be uninstalled by selecting the entry and clicking [Remove].

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 connectors 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;

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

You do not need a new license key when upgrading an existing installation. The installer will not ask you for a license key.

Upgrading migration-center will keep all existing configuration and data.

Please stop any running jobs (scanners, importers, schedulers, transformations, validations) before starting the upgrade.

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

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 the FileSystem connector) some additional checks are done by the 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 connector. 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:

Please backup your migration-center Database before upgrading it.

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 Install 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