Working of Migration Utility for Runtimedata Migration

In order to understand the working of the utility, it is important to understand the structure of runtimedata which is explained below.

Runtimedata Structure

The runtimedata directory present inside $NEW_FIORANO_HOME directory contains the following information:

• Event Process Repository: Repository of User created EventProcess(es) and any modified pre-built Event Process(es). This information is present under $NEW_FIORANO_HOME/runtimedata/repository/applications directory.
• Component Repository: Repository of User created Component(s) and any modified pre-built component(s). This information is present under $NEW_FIORANO_HOME/runtimedata/repository/components directory.
• Schema Repository: Repository of external schemas referred by schema of the component ports.This information is present under $NEW_FIORANO_HOME/runtimedata/repository/Schemas directory.
• Events and SBW Database: The database files containing events and SBW database. The information is present under $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/doctracking_db and $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/events_db. These directories will be present only if Enterprise Server was using the default H2 database shipped with the product.
• Peer Server Component Cache: Cache of the components with all resources used by Peer Servers to launch the components. This cache is created for each Peer Server profile separately. The cache is present under $NEW_FIORANO_HOME/runtimedata/PeerServers/<PeerServerProfileName>/FPS/run/components.
• Peer Server Profile Cache: Cache of the connected Peer profiles maintained by each Enterprise Server. This cache is present under $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/peers directory.
• Logs: Log Files for the Servers and components. The log files are created under runtimedata for each Server Profile separately. This information is present under $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/run/logs for an Enterprise Server profile and $NEW_FIORANO_HOME/runtimedata/PeerServers/<PeerServerProfileName>/FPS/run/logs for a Peer Server profile.
• Realm Store: Realm Store (containing users, groups and ACLs) used by the Server. This information is present under each profile directory. A typical example of the directory containing this information would be $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/run/SDB.
• File Based Data Store: Data Stores (containing persistent data for Topics and Queues) used by the Server. This information is present under each profile directory. Few examples of the directory containing this information would be $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/run/PTP and $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/run/PUBSUB and $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/run/PSQ.
• eStudio runtimedata: This information is present under FIORANO_HOME/runtimedata/eStudio/workspace directory.

eStudio has two kinds of repositories - Offline and Online.

• • Online repository is dynamic and is created when we log in into an Enterprise Server. Only the Enterprise Server nodes configuration is stored in online repository and the same is migrated when we run the utility.
  • Offline repository holds the Event Processes, Services created in the Offline Event Process Development perspective and the mapper projects created in the Mapper perspective.

All the Event Processes and Mapper projects created in Offline mode will be migrated when the migration utility is run.

Services have to be migrated manually and the section 'Migrating Offline Services from eStudio' will give a detailed explanation of this process.

• Studio runtimedata: This information is present under $NEW_FIORANO_HOME/runtimedata/Studio directory. Studio uses this directory to persist, store and cache any information while running.

Thus, by copying runtimedata from previous installation to new installation, we can make sure that almost all the configurations done in the previous installation are ported to new installation. Out of the information explained above, the following information need not be migrated to new installation (next section explains the reasons):

• Cache of the components maintained by the Peer Servers. Peer Server automatically creates this cache at the time of Component Resource and Connectivity Check (CRC).
• Log Files for the Servers and components.
• Cache of the Peer Profiles maintained by Enterprise Server.

The next section explains the steps followed by the utility to migrate runtimedata directory. The procedure begins with copying the entire runtimedata directory from previous installation to the new Fiorano installation and then removing the un-necessary data (if required).

How does the Utility work?

The utility performs 4 types of tasks

1. Migrating Server runtimedata
2. Migrating eStudio runtimedata
3. Migrating Studio runtimedata
4. Migrating from Replicated HA to Shared HA

Migrating Server Runtimedata

In order to migrate the runtimedata, the utility copies the runtimedata created for each profile to $NEW_FIORANO_HOME directory. After this step, it proceeds with clearing un-necessary and unwanted data from the copied data.

Clearing Peer Server Profile Cache

It is essential to delete Peer Server Profile Cache maintained by Enterprise Server due to profile structure changes in the new Fiorano installation w.r.t. previous versions. This step will delete the directory $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<EnterpriseServerProfileName>/FES/peers (This step will be executed for each Enterprise Server profile).

Clearing Enterprise Server's User Component Repository

As already pointed out, Enterprise Server's User Component Repository is located at $NEW_FIORANO_HOME/runtimedata/repository/components directory. This repository contains user created components as well as pre-built components that have been modified by the user.

As pre-built Fiorano components might change from one release to another either in terms of code-base or the resources/dependencies required by them, it is essential to delete these components (if they exist) from User Component Repository so that the servers do not use old components. Before deleting any pre-built Fiorano component from User Component Repository, it will be backed up in $NEW_FIORANO_HOME/runtimedata/repository/components_bkp for reference purposes.

Clearing Server and Component Log Files

Though this step is not mandatory, it helps to keep the new installation clean. This step will delete the Server logs and also the log files for the components. This may also help in debugging and solving an issue (if it occurs), as we will know for sure that the issue occurred in this installation and not in the previous one. For each profile, following directories will be deleted from $NEW_FIORANO_HOME/runtimedata (All paths below are relative to this directory).

• EnterpriseServers/<EnterpriseServerProfileName>/FES/run/logs

  Icon

  This step will be executed for each Enterprise Server profile.

• PeerServers/<PeerServerProfileName>/FPS/run/logs

  Icon

  This step will be executed for each Peer Server profile. Deleting this directory also deletes log files created by components running on this Peer Server.

Clearing Peer Server Component Cache

This step will delete the directory $NEW_FIORANO_HOME/runtimedata/PeerServers/<PeerServerProfileName>/FPS/run/components.

Clearing Server Realm Store

Prior to Fiorano 9.1.0 release, Enterprise Server maintained 2 realm stores. One required by JMS layer and another required by Enterprise Server layer. These two stores could be located as:

1. $OLD_FIORANO_HOME/runtimedata/EnterpriseServers/<profileName>/FES/run/SDB
2. $OLD_FIORANO_HOME/runtimedata/EnterpriseServers/<profileName>/FES/run/db/PersistantDB/TifosiSDB/REALM_USER

With Fiorano 9.1.0 release, the 2 realm stores present in Enterprise Server were unified to a single store. Since then, all realm information is present in $NEW_FIORANO_HOME/runtimedata/EnterpriseServers/<profileName>/FES/run/SDB directory. If migration is being performed from versions prior to Fiorano 9.1.0, the migration scripts will delete these two stores and any users/groups created in Enterprise Server layer have to be created again after migration. Moreover, whenever a Peer Server connects to Enterprise Server, Principal Store (User & Group Store) of Enterprise Server will be sent to Peer Server, where Peer Server will try to over-write its own Principal Store with that of Enterprise Server's store. This is a step-by-step operation where extra users/groups are deleted and missing users/groups are added to Peer Server's Principal Store. If there is an exception in any of the step, Peer Server store will be marked as unsynchronized and the reason for un-synchronization will be displayed in dashboard (refer the RDBMS Realm section in Fiorano Online User Guide for more information). Starting Fiorano 9.1.0, synchronized store is a mandatory condition to be able to launch an Event Process on a particular Peer Server.

These exceptions will happen only if migration is performed from versions older than Fiorano 9.1.0. Users of Fiorano 9.1.0 or later will not see these exceptions if their current installation does not have them already. Usually the exceptions happen while synchronization if a user/group marked for deletion in Peer server is bound to an ACL(Access Control List), in which case it will not be deleted from Peer Server's store. On seeing such a message in dashboard, user should take manual steps to either free the user from the ACL or create a similar user in Enterprise Server and then re-sync the Principal Store of concerned Peer Server with Enterprise Server using dashboard. As these problems can happen only if Realm Stores are migrated from versions older than Fiorano 9.1.0, we have provided an option in runtimedatamigration scripts which asks whether Realm Store needs to be migrated or not. If user chooses the option no, SDB directory will not be copied over to new installation and users/groups will be created afresh when servers are started up. In this case, all users/groups manually created in previous installation will have to be re-created in new installation as well.

Migrating eStudio Runtimedata

When the migration utility is run, the data to be migrated from the previous version of Fiorano installation ($FIORANO_HOME/runtimedata/eStudio/workspace/.repositories) will be copied to the new installation. All the necessary folder structure in the new installation will be automatically created when the utility is run.

Migrating Studio Runtimedata

This step will first copy Studio runtimedata directory to new installation and then remove unwanted data as explained below:

• Delete the directories $NEW_FIORANO_HOME/runtimedata/Studio/<OldBuildNumber>/cache and $NEW_FIORANO_HOME/runtimedata/Studio/<OldBuildNumber>/var. These directories contain the cached information used by the Studio. These directories will be auto-created again whenever Studio starts up.
• Rename the directory $NEW_FIORANO_HOME/runtimedata/Studio/<OldBuildNumber> to $NEW_FIORANO10.3.1 /runtimedata/Studio/<NewBuildNumber>.

Migrating from Replicated HA to Shared HA

Migrating from Replicated HA to Shared HA would require configuring the Shared HA profiles from scratch. This can be easily done via Studio Profile Editor in the same way as for Replicated HA profiles. Please refer the High Availability Server in Shared Mode section for more information.

To use the EventProcesses, components, users, groups, ACLs, and so on created in a Replicated Server, user can copy the part of runtimedata corresponding to that particular Replicated Server Profile into the Shared HA Database. For example, if Shared HA Servers are using the directory /home/shared_db_fes as runtime database directory for Enterprise Server (and /home/shared_db_fps as runtime database directory for Peer Server) and there is a need for Shared HA Servers to use the Replicated HA runtime database (to avoid the pain of creating users, groups, ACLs etc. and importing, exporting the Event Processes), the utility performs the following sequence of steps:

For Enterprise Server Profiles

• Copy the contents of $OLD_FIORANO_HOME/runtimedata/EnterpriseServers/<ReplicatedHAProfileName>/FES/run and paste it into the runtime database directory (/home/shared_db_fes in this case) used by Shared HA Servers.

  Icon

  Here, <ReplicatedHAProfileName> can be taken as either that of primary server or secondary server. As both primary and secondary databases are in sync at all time, it won't matter as to which database is copied.

• Copy $OLD_FIORANO_HOME/runtimedata/repository directory and paste it into runtime database directory (/home/shared_db_fes in this case) used by Shared HA Servers.
• Delete logs directory (that is, /home/shared_db_fes/logs). This step is not mandatory.
• Delete haStatus.dat file (that is, /home/shared_db_fes/haStatus.dat file). This is required as the set of Server States in Replicated HA Servers is not same as that of Shared HA Server.

For Peer Server Profiles

• Copy the contents of $OLD_FIORANO_HOME/runtimedata/PeerServers/<ReplicatedHAProfileName>/FPS/run and paste it into the runtime database directory (/home/shared_db_fps in this case) used by Shared HA Servers.

  Icon

  Here, <ReplicatedHAProfileName> can be taken as either that of primary server or secondary server. As both primary and secondary databases are in sync at all time, it won't matter as to which database is copied.

• Delete logs directory (that is, /home/shared_db_fps/logs). This step is not mandatory.
• Delete Peer Server Component Cache directory (i.e. /home/shared_db_fps/components).
• Delete haStatus.dat file (that is, /home/shared_db_fps/haStatus.dat file). This is required as the set of Server States in Replicated HA Servers is not same as that of Shared HA Server.

HA Behavior Difference

The HA logic has been significantly modified since Fiorano 2007 SP7 release (Refer the High Availability section). Some of the newly added parameters are briefly explained below:

• LockFile: This parameter specifies the path of a file on which an HA Server will try to obtain lock before turning to ACTIVE state. A pair of HA Server, that is, Primary/Secondary servers should share the same physical LockFile.
• GatewayServerIPAddress: This parameter specifies the IP address/hostname of the machine hosting the LockFile.
• BackupRMIServerPort: This parameter specifies the RMI port of the backup Server.

For more details on working of HA mechanism, please refer the High Availability section.

Due to these additional parameters, it may be necessary to re-configure old HA profiles after migrating them to the new Fiorano Version.