Migration Process using Zip Files

One way to export and import the migration project from a source server to a target server is using a zip file. The high level steps involved in this process are:

Run Migration Project Export Process to create a Migration Project package zip file.
Receive the Migration Project Export Package via email or file system.
Import the Migration Project package zip file.

Obviously, for many use cases the above steps are not sufficient; e.g. if the source domain differs from the target domain there must be a step which modifies the content of the package file before import. It is also possible that a configuration is required to be managed by a Version Source Control System and so in theory the package file to be imported could be manually generated and not always the direct result of an Export process.

Creating the Migration Project Package

The migration project defines specific objects that are considered part of the project but it does not contain any of the content associated with each object. It is essentially just a list of unique keys.

Running the Export process (Business Process Automation > Process Management > Migration Project Export) extracts the content for all (valid) project objects and packages it along with a Project Control File (project.xml) into a Migration Project Package zip file.

The package file name (i.e. preceding the default file extension of “.zip”) will default to the Migration Project XID but can be overridden by using the Migration Project Package field.

In an OTM environment with multiple application servers it becomes necessary to specify which server should execute the Export and Import processing. This is to fix the location for the package files to be one server. If this was not done, then if the package is not copied to ALL servers, it is possible that a scheduled Import process could fail.

Therefore, in a Scalability configuration the following steps should be taken:

Use Cluster Management to define a new cluster for Migration Project Processes
Assign one machine to this cluster.
Associate the MIGRATION Application Function to the new cluster.
Restart Application servers.

Note: The physical location on the server where the package file is stored is controlled by the glog.migrationProject.dir property and defaults to <OTM_HOME>/glog/integration/projects. To protect hosted systems, this reserved property cannot be changed in the cloud with a service request.

The option also exists to receive the exported package file by email (by subscribing to MIGRATION PROJECT – EXPORT SEND PACKAGE FILE event. See below).

Receiving Migration Project Export Packages via Email

The exported migration project package can be received by using an email. In order to receive via email, you have the below options.

Contact Notification
Contact Manager
Automation Agent

When sending attachments via email, you must consider the file extension of the package file. Some email servers do not permit the “.zip” extension for security reasons. By default, the Migration Project Package file will use the “.zop” file extension. You can change the file extension by setting the “glog.migrationproject.export.email.extension” property. For example, glog.migrationproject.export.email.extension=zap.

Contact Notification

One method is to create a contact notification for the contact.

Go to the Contact Notification page (Business Process Automation > Communication Management > Contact Notification).
Search for the Notify Function ID of "MIGRATION_PROJECT_EVENT".
Edit the "MIGRATION PROJECT - EXPORT SEND PACKAGE FILE".
In the Contacts section, specify the contact you want to receive the migration project export package.
Set the Communication Method to "EMAIL".
Click Save.
In the Communication Methods section, set the Communication Method of "EMAIL".
Enter the Stylesheet of "MIGRATION_PROJECT_EVENT_BY_EMAIL".
Select the Default check box.
Click Save.
Click Finished.

Contact Manager

To register the contact to receive notifications for the event:

Go to the Notification tab on the Contact Manager page (Business Process Automation > Communication Management > Contacts > Notification tab).
In the Subject field, enter "MIGRATION PROJECT - EXPORT SEND PACKAGE FILE".
Enter "EMAIL" in the Com Method field.
Click Save.
Click Finished.

Automation Agent

Optionally you can create an automation agent to send the email.

Go to the Automation Agent page (Business Process Automation > Agents and Milestones > Automation Agent).
Create a new agent with the Agent Type of "Migration Project".
Click View/Enter Actions.
Click Add Action.
Select the Action of "NOTIFY CONTACT".
Enter the Contact.
Select the Communication Method of "EMAIL".
Click Save.
Click Finished.

Migration Project Package File Contents

In the current release, the object content is stored in DB.XML format files where there will be one DB.XML for each migration object group.

The DBXML Export by “Migration Entity” capability is used to extract the content for the project package.

The Migration Entity name used is based on the table name associated to the Screen Set ID for each object group.

The content of a sample project package with one LOCATION object group is listed below:

$ jar tvf $OTM_HOME/glog/integration/projects/TEST-001.zip

3380 Tue Jul 30 10:39:54 PDT 2013 LOCATION_1.db.xml

785 Tue Jul 30 10:39:54 PDT 2013 project.xml

The project.xml file is the Project Control File and contains information on the contents of the package (described in MigrationProject.xsd): -

ID of source project
Status of source project on export
Version of source project on export
Number of object groups in source project
Number of object groups successfully exported to this package
Start/End process times for export.
For each group: -
- Transaction code
- Process sequence
- Number of objects in the source group
- Number of objects successfully exported to package
- Object IDs in group.

Content Modification

There may be occasions where some of the data elements in the source system differ from the required corresponding elements in the target system e.g. domain name, email address, external system URL etc.

If this is the case, the relevant DBXML source file must be unpacked from the package, edited and then repackaged using the same file name as in the original package file.

Importing a Migration Project Package

Go to Business Process Automation >Process Management >Migration Project Import.

In order to import select the “Import Using Zip File” option.

The import process takes a migration project package and uploads the content contained within it.

By default, it will create a new migration project in the importing (target) system to record the groups and object IDs of the imported data and the success or failure of each import.

The package file can be uploaded (referred to as Local) at the time of submitting the Migration Project Import Process or already resident on the Application server (referred to as Server) in which case it must be located in the directory specified by the glog.migrationProject.dir property which defaults to <OTM_HOME>/glog/integration/projects.

If no Migration Project ID is specified, the import process will generate a new ID which is a combination of the current date and a unique sequence i.e. YYYYMMDD-nnnn.

If an existing Migration Project ID is specified, the current import will replace all groups and objects in that project with the content from the current project package.

There is an option to control how to react if/when an error occurs in processing the content – Action On Error – and can be one of: -

CONTINUE: mark group/object as ERROR status and attempt next group.
FAIL: stop processing immediately and mark project as ERROR.