Migration Utility

User Guide
Version 3.0

Release Date December 12, 2007

Adeptia Inc.
443 North Clark Ave,
Suite 350
Chicago, IL 60610, USA
Phone: (312) 229-1727
Copyright

Copyright © 2000-2007 Adeptia, Inc. All rights reserved.

Trademarks

The Adeptia logo and Manage, Automate and Optimize Business Processes are trademarks of
Adeptia, Inc.

Statement of Conditions

Adeptia, Inc. provides this publication "as is" without warranty of any kind, either express or
implied. In no event shall Adeptia be liable for any loss of profits, loss of business, loss of use or
data, interruption of business, or for indirect, special, punitive, incidental, or consequential
damages of any kind.

No part of this work covered by copyright herein may be reproduced in any form or by any
means—graphic, electronic or mechanical—including photocopying, recording, taping, or storage
in an information retrieval system, without prior written permission of the copyright owner.

This publication is subject to replacement by a later edition. To determine if a later edition exists,
contact www.adeptia.com .

Contact Information

In case of any queries, please contact us at:

Contact For Email ID

Sales [email protected]
Support [email protected]

For more information, you can visit us at www.adeptia.com

 Table of Contents

1 INTRODUCTION................................................................................................................................ 3
NEED FOR MIGRATION .............................................................................................................................. 3
ADEPTIA MIGRATION UTILITY................................................................................................................... 3
BENEFITS OF USING ADEPTIA MIGRATION UTILITY ................................................................................ 4
2 GETTING STARTED.......................................................................................................................... 5
PRE-REQUISITES ........................................................................................................................................ 5
STARTING ADEPTIA MIGRATION UTILITY ................................................................................................ 5
3 ENVIRONMENT PROMOTION .................................................................................................... 7
EXPORT ....................................................................................................................................................... 8
PROMOTE .................................................................................................................................................. 13
Generating XML for Retained Objects in the Target System ......................................... 21
Deleting an Object.......................................................................................................................... 29
DEPLOY ..................................................................................................................................................... 31
4 MIGRATION....................................................................................................................................... 34
ONLINE MIGRATION ................................................................................................................................ 35
OFF LINE MIGRATION.............................................................................................................................. 38
Export/Backup ................................................................................................................................. 39
Import/Restore ................................................................................................................................ 41
5 PATCH UPDATE ............................................................................................................................... 48
APPLY PATCH ............................................................................................................................................ 49
REMOVE PATCH ........................................................................................................................................ 52
6 APPENDIX A...................................................................................................................................... 55
SAMPLE CONFIGURATION VALUES ......................................................................................................... 55
SQL Server Database .................................................................................................................... 55
HSQLDB Database.......................................................................................................................... 55
Default Values for Additional Columns in an Upgraded Version................................... 55
7 TABLE OF FIGURES ....................................................................................................................... 57
8 TABLE OF TABLES .......................................................................................................................... 59

Adeptia Migration Utility User Guide 2

1 INTRODUCTION

NEED FOR MIGRATION

At times while working with an Adeptia product, you may come across a situation, where you
need to change a process flow or an object. For this, you need to transfer the objects across
multiple environments, such as change the object in the Development environment, test it in
the QA environment and finally apply the changes in the Production environment. Alternately,
when an upgrade of an Adeptia product is released, you need to migrate all the data from the
earlier version to the upgraded version. This can be quite a cumbersome process, as once you
transfer the objects, you cannot rollback the action.

ADEPTIA MIGRATION UTILITY

Adeptia offers a Migration utility which facilitates you to seamlessly migrate objects in all
situations. It is a comprehensive tool which enables you to:

ƒ Promote objects across environments (for example, Development environment to

QA environment, or QA environment to Production environment)
ƒ Migrate objects from an older version to a new upgrade version
ƒ Change the backend database
ƒ Take backup of the Adeptia Server

This tool allows you to transfer objects in three ways:

ƒ Environment Promotion: It allows you to promote objects across environments.
This is migration at the user level, where you can select a group and promote all
its objects such as Events, Activities, Process Flows, Users and Groups, to another
environment. In environment promotion logs data and transaction states are not
transferred to new environment.
ƒ Migration: It allows you to migrate objects across versions. This is migration at
an advanced level, where you can transfer all objects of all groups in the currently
installed version to a new upgraded version. Additionally, it also facilitates you to
take a backup of all objects and configuration files in the current installation and
restore them whenever required.
ƒ Patch Update: It allows you to update the patch over existing Adeptia Server. It
replaces the files which are in patch and change the backend database as per the
query written in patch.

After migration all Events are de-activated in new environment.

Adeptia Migration Utility User Guide 3

BENEFITS OF USING ADEPTIA MIGRATION UTILITY

The benefits of using the Adeptia Migration utility are outlined as:

ƒ Provides an automated means of object transfer across environments and versions

ƒ Provides options of transferring all objects or selected objects based on a group,
objects within a group or even fields within an object
ƒ Maintains an Audit log of all actions performed in the object transfer
ƒ Rollbacks the entire operation if an error occurs. If the migration is successful, it
cannot be rollbacked.
ƒ Allows you to take a backup of all objects so that they can be restored whenever
required.

Adeptia Migration Utility User Guide 4

2 GETTING STARTED
PRE-REQUISITES
The pre-requisites of using the Migration utility are outlined as:
ƒ Java Runtime Environment (JRE) 1.5
ƒ The database of the Adeptia Server should be running. In case of HSQLDB, you need to
ensure that the kernel is running, as it activates the backend database of the server. In
other databases, the kernel is not required to be running, however if it is running, it will
not affect the migration utility.
ƒ Ensure that no objects are created or modified during the Migration process

STARTING ADEPTIA MIGRATION UTILITY

You can run the Migration utility on:

ƒ Server
ƒ Desktop

The Migration utility is either bundled with the Adeptia Server or it can be downloaded or
purchased separately. To run it on a desktop, you need to copy the utility explicitly on the
desktop.

It is recommended that you run the utility on the Adeptia Server, as

some parts of the utility can be run on the Server only.

When you run the utility, the system creates a log file in the same location as the utility file.
Each time you run the utility; this log is appended.

Steps to start the Adeptia Migration Utility

1. Double-click the Migration utility file (MigrationUtilityv3.0.exe). The Adeptia
Migration wizard is displayed (see Figure 2.1).

Adeptia Migration Utility User Guide 5

 Figure 2.1: Adeptia Migration Utility screen
2. Click Next. The Select action screen is displayed (see Figure 2.2).

Figure 2.2: Select Action screen

3. Select the appropriate radio button and click Next. The subsequent screens
are displayed based on the selected option. If you select Environment
promotion option, refer to Environment Promotion section. If you select
Migration option, refer to Migration section. If you select the Patch Update,
refer to the Patch Update section.

Adeptia Migration Utility User Guide 6

3 ENVIRONMENT PROMOTION
You can use Environment Promotion to transfer objects of selected groups from one
environment to another. This implies that you need to select a group and then transfer the
objects of that selected group.
For example, a project is in Production stage, and a few enhancements are requested by the
client. To incorporate these enhancements, the project will have to be transferred across
various environments. The objects of the project will be changed in the Development
environment. Once the changes are done, they will be internally tested, before the project is
sent to the QA environment, where it is thoroughly tested again. Once the QA team is done, it
will send the project to the Production environment.
Instead of transferring the entire project, which could take time, you can just transfer the
objects that have been changed. The Migration utility allows you to create a zip file of all the
changed objects and promote them across the three environments.

Steps to promote objects using Environment Promotion

Environment Promotion is a three-step process.
1. Select the Environment Promotion radio button on the Select Action screen
and click Next. This displays the Environment Promotion actions screen (see
Figure 3.1).

Figure 3.1: Environment Promotion Actions screen

This screen displays the three steps used in the Environment Promotion. These are outlined in
the table below.

Adeptia Migration Utility User Guide 7

 Table 3.1: Environment Promotion Actions
Action Description

Export Allows you to export objects from the source

file to a zip file.
Promote Allows you to select objects from exported zip
file, compare it with the target system and
generate another zip file for the changes you
want to update to the target system.
Deploy Allows you to apply the promoted changes to
the target system.

EXPORT

This step is performed on the source system where the Adeptia Server is installed.
Steps to export objects
1. Select the Export radio button on the Environment Promotion Actions screen
and click Next. The Select Source System screen is displayed. Click Browse
to select the directory where the Adeptia Server is installed (see Figure 3.2)

Figure 3.2: Select Source System Install Directory

2. Click Next. This displays the Select Group screen (see Figure 3.3).

Adeptia Migration Utility User Guide 8

 Figure 3.3: Select Group
3. This screen displays a list of all the groups in the Adeptia Server. Check the
checkbox against the group, whose objects you want to export.

You can select one or more groups.

4. Click Next. The Select Objects screen is displayed (see Figure 3.4).

Figure 3.4: Select the Action

5. Select the objects that you want to export. You can either export all objects of
the selected groups or only all process flows and their associated objects.

Adeptia Migration Utility User Guide 9

 Click the appropriate radio button. If you have selected multiple groups in the
Select Group screen and you select the Process Flow Objects option in this
screen, then all objects associated with all Process Flows are exported.
However, if you have selected only one group in the Select Group screen, then
selecting the Process Flow Objects option, will display the Select Process Flow
screen (see Figure 3.5).

Figure 3.5: Select Process Flows

6. This screen displays a list of all the process flows for the selected group.
Check the checkbox against the process flow that you want to export.

If you select All Objects option in Select the Action screen, the Select
Services screen is displayed (see Figure 3.6). In Select Services screen
you can select all services or only the required services to export. To
select all services click Select All button. To select the individual
services check the checkbox against the required services.

Adeptia Migration Utility User Guide 10

 Figure 3.6: Select Service

Some service names have changed across the version and because of
that some service may be shown multiple times with different names.
Following table shows those services and their name.

Table 3.2: Services and their name which have changed

Current Service Name Old Service Names

Data Mapping Mapping Transformation

Custom Plugin Scripted Service
Database Event DBEvent

7. Click Next. The Select Target directory screen is displayed. Click Browse to
select the target location where you want to save the zip file (see Figure 3.7).

Adeptia Migration Utility User Guide 11

 Figure 3.7: Select Target Directory
8. Click Next to start the export process. The progress of this process is
displayed in the View Logs screen (see Figure 3.8).

Figure 3.8: View Export Logs

This screen displays all logs and confirms whether the export operation is successful or
not. If it is successful, a message stating “Export completed successfully” is displayed in
the View Export Logs screen and as a popup window, and a zip file of the exported objects
is created. In case of failure, it displays an error message in the View Export Logs screen
and as a popup window, and rollbacks the entire operation.

Adeptia Migration Utility User Guide 12

 Clicking Clear Logs clears all logs in the View Export Logs screen, but
not in the back end.
Clicking Save Logs saves all logs in the View Export Logs screen.

9. Click Finish to complete the export process and exit the Migration utility.

PROMOTE
This step is performed on the target system.
Pre-Requisite
ƒ The exported zip file must be available on the target system on which the Adeptia
Server is installed.

Steps to Promote objects:

1. Select the Promote radio button on the Environment Promotion Actions screen
and click Next. The Select Source Location screen is displayed. Click Browse
to select the zip file that was created in the Export process (see Figure 3.9).

Figure 3.9: Select Source Location

2. Click Next. This displays the Select Target Directory screen. Click Browse to
select the directory, where the target system on which the Adeptia Server is
installed (see Figure 3.10).

Adeptia Migration Utility User Guide 13

 Figure 3.10: Select Target System Install Directory
3. Click Next. This displays the Select Group screen (see Figure 3.11).

Figure 3.11: Select Group

4. This screen displays a list of all the groups in the Adeptia Server. Check the
checkbox against the group whose objects you want to promote.

You can select one or more groups.

5. Click Compare Selected Objects to compare the source and target objects.
It displays the process in running state (see Figure 3.12).

Adeptia Migration Utility User Guide 14

 Figure 3.12: Generating Compare Selected Objects Process
6. Once the process is complete, the Compare Objects screen is displayed (see
Figure 3.13).

Figure 3.13: Compare Objects (Process Flow Objects)

If you had selected the All Objects option in Select the Action screen in the Export process,
then the Compare Objects screen will be displayed as below.

Adeptia Migration Utility User Guide 15

 Figure 3.14: Compare Objects (All Objects)

Objects of the selected groups are displayed in this screen. The

unselected groups are ignored and not listed.

7. The Compare Objects screen displays objects in a tree structure, which shows
a comparison between the source and target objects at both the activity and
field levels. It displays legends at the activity and field levels, which highlight
the comparison and indicate whether the activity or field will be updated or
not. It also displays the Advanced Properties of the object at the field level.
The legends are displayed at the bottom of the screen and are outlined in the
table below.

Table 3.3: Legends on the Compare Objects screen

Legend Description

Source and target objects are different. Once the

source objects are promoted, the target objects will

Adeptia Migration Utility User Guide 16

 be updated.
Source and target objects are the same. Thus,
promotion is not required in this case.
New record will be inserted from the source end to
the target end, as the target database has additional
parameters.
No source data exists for the particular target field.

When the source and target objects are different, they need to be updated at the
target end. This is done by comparing the Activity ID of the objects at the source and
target end. If they match, then the objects are updated, else not.

You can delete an object from the Compare Objects screen. Refer to
the Deleting an Object screen.

8. You can view the changes between the source and target end by right-clicking
each field/activity, and selecting View Changes option (see Figure 3.15).

Figure 3.15: Select View Changes option

Adeptia Migration Utility User Guide 17

 9. The View Difference screen is displayed (see Figure 3.16).

Figure 3.16: View Difference

10. This screen displays the Source and Target columns, which show the actual
value of the attribute at the source and target ends. You can change the value
in the Source Data column and click Update. This saves the modified value
and updates it at the target end. The Target column is non-editable. So, to
change a target object, you need to change its source object.

At times, the Source and Target columns are displayed as empty. If the
Source column is empty, it indicates that the fields are blank at the
source end. The Target column is empty if there is no object at the
target end.

11. Click Close to close this screen and return to the Compare Objects screen.
Similarly, click Close to close this screen and return to Select Group screen.
12. Click Next. The Select Retain XML Location screen is displayed. Click Browse
to select the location where the xml file for the objects to be retained, is
stored (see Figure 3.17 Error! Reference source not found.).

Adeptia Migration Utility User Guide 18

 Figure 3.17: Select Retain XML Location

If you are starting the Migration tool for the first time, or you want to
edit the existing xml file, refer to the Generating XML for Retained
Objects in the Target System section.

13. Click Next. This displays a screen, where you need to enter your name in the
specified field. This is just to keep track of who approved the promoted objects
(see Figure 3.18).

Figure 3.18: Enter username

Adeptia Migration Utility User Guide 19

 14. Click Next. The Select Target location screen is displayed. Click Browse to
select the target location where you want to save the zip file created in the
Promotion process (see Figure 3.19).

Figure 3.19: Select Target Location for Promoted Objects

15. Click Next to start the Promote process. The progress of this process is
displayed in the View Promoted Logs screen (see Figure 3.20).

Figure 3.20: View Promoted Logs

This screen displays all logs and confirms whether the promote operation is successful or
not. If it is successful, a message stating, “Promoting objects completed successfully” is
displayed in the View Promoted Logs screen and as a popup window, and a zip file of the

Adeptia Migration Utility User Guide 20

 promoted objects is created. In case of failure, it displays an error message in the View
Promoted Logs and as a popup window, and rollbacks the entire operation.
16. Click View PDF Report to view a list of all records that will be updated and
inserted in the target system in the Deployment state. A record is inserted at
the target end, when data at the source and target end differ.

The Report feature is available only in the Promote step.

17. Save the PDF report and then open it to view its details (see Figure 3.21).

Figure 3.21: View PDF Report

18. Click Close to close this screen and return to the View Promoted Logs screen.
19. Click Finish to complete the promote process and exit the Migration utility.

GENERATING XML FOR RETAINED OBJECTS IN THE TARGET SYSTEM

While promoting objects, you may want to retain a few objects at the target end. For
objects that are specific to the environment, or configuration objects such as User ID, you
do not want to promote and overwrite them at the target end. For example, when
promoting data from the Development environment to the Production environment, the
Database Info objects may vary. The objects are the same, but their connection

Adeptia Migration Utility User Guide 21

 parameters are different. You do not want to overwrite the connection parameters at the
target end. The Adeptia migration utility allows you to retain the objects by creating an
xml of the objects.

1. Click Generate Retain XML on the Select Retain XML Location screen to
select the objects to be retained. This displays the process in the running state
(see Figure 3.22).

Figure 3.22: Generate Retain List Process

2. Once the process is complete, the Retain List is generated (see Figure 3.23).

Figure 3.23: Retain List

Adeptia Migration Utility User Guide 22

 3. This list displays all the objects of the Adeptia Server in a tree-like structure. It
has two levels:
ƒ Service Level
ƒ Field Level

You can retain objects at both the Service and Field Levels but at a
time you can retain object either at service label or field label.

Retaining Objects at Service Level

You can retain an entire service from being transferred. For example, you may want to
retain all objects of the Mail Target service. So, instead of individually retaining each
object, you can retain the entire Mail Target service. This implies that when the data is
transferred, the Mail Target service at the source end will be ignored, and not transferred.
Steps to retain objects at Service level
1. Check the checkbox against the service that you want to retain.

You can expand the service by clicking [+] against the service. All
fields associated with the activity are displayed. However, they are de-
active and cannot be selected.

2. To retain a specific activity of the service, right-click the service and select
Specific Activity option (see Figure 3.24).

Adeptia Migration Utility User Guide 23

 Figure 3.24: Select Specific Activity Option
3. This displays the Retain Activity Query Builder screen (see Figure 3.25).

Adeptia Migration Utility User Guide 24

 Figure 3.25: Retain Activity Query Builder
4. Specify the criteria on the basis of which the service will be ignored, by
entering the activity name and ID in their respective fields.

You can either enter values in both the Activity Name and Activity ID
fields, or in one field only. However, it is mandatory to enter value in
one field.
If you do not remember the ID of an activity, you can refer to the
Production environment or go to the Manage section of the Adeptia
Server.

5. Click Insert. This displays the activity name and ID in the Query Information
field (see Figure 3.26).

Adeptia Migration Utility User Guide 25

 Figure 3.26: Activity Name Displayed in the Query Information Field

You can specify one or more activities in this screen. All the specified
activities are listed as comma separated values in the Query
Information field.
You can remove an activity listed in this field, by selecting the activity
and pressing <Delete> on the keyboard.

6. Click Done to complete the query and return to the previous screen (refer to
Figure 3.24).
7. Click Generate Retain XML. This generates the xml file for the retained
service. This implies that when transferring data, the selected service for the
specified activities will be ignored at the source end and not overwritten at the
target end.

Retaining Objects at Field Level

At times, you may want to retain values of a specific field only. For example, while
transferring data, you want to retain the UserID and Password values of the Mail Target
activity. You can retain these fields using the Migration tool. Thus, when data is
transferred, values in the UserID and Password fields will be ignored at the source end and
not overwritten at the target end.
Steps to retain objects at Field level
1. Click [+] to expand the activity whose field you want to retain. A list of all
fields associated with the service is displayed (see Figure 3.27).

Adeptia Migration Utility User Guide 26

 Figure 3.27: Fields associated with a Service
2. Check the checkbox of the field that you want to retain. This will retain the
field for all objects of the selected service (see Figure 3.28).

Adeptia Migration Utility User Guide 27

 Figure 3.28: Select Field
3. To retain the field for a specific service, right-click the field and select Select
Activity option. This displays the Retain Activity Query Builder screen.
4. Specify the criteria on the basis of which the activity will be ignored, by
entering the activity name and ID in their respective fields.

You can either enter values in both the Activity Name and Activity ID
fields, or in one field only. However, it is mandatory to enter value in
one field.
If you do not remember the ID of an activity, you can refer to the
Production environment or go to the Manage section of the Adeptia
Server.

5. Click Insert. This displays the activity name and ID in the Query Information
field (refer to Figure 3.26).

You can specify one or more activities in this screen. All the specified
activities are listed as comma separated values in the Query
Information field.
You can remove an activity listed in this field, by selecting the activity
and pressing <Delete> on the keyboard.

Adeptia Migration Utility User Guide 28

 6. Click Done to complete the query and return to the previous screen (refer to
Figure 3.24).
7. Click Generate Retain XML. This generates the xml file for the retained
activity. This implies that when transferring data, the field values of the
specified activity will be ignored at the source end and not overwritten at the
target end.

The objects that are changed at the Field level are displayed in the
Compare Objects screen with the legend. And if you want to retain
this value of the target side, the changed value is extracted from the
target and transferred to the source, thus implying that the values are
same at the source and target end. For example, if the File Path field of
the File Source service is changed, then the updated value is extracted
from the target end and transferred to the source end of the File Path
field. This field is now displayed in the Compare Objects screen with
the legend.

DELETING AN OBJECT
While comparing the objects, you can delete an object.
Steps to delete an object
1. Right-click the object you want to delete in the Compare Objects screen, and
select the Delete option (see Figure 3.29).

Adeptia Migration Utility User Guide 29

 Figure 3.29: Select Delete Option
The selected object is deleted from the list.

You can delete objects at the Service, Process Flow and Activity levels.
However, you can update only at the Field level.

If you delete an object at the Service level, then the entire service along with its process flows
and activities is deleted. If you delete an object at the Process Flow level, then all process
flows and its objects are deleted. If you delete an object at the Activity level, then the entire
activity along with its fields is deleted.

Adeptia Migration Utility User Guide 30

DEPLOY

The Deploy step allows you to apply the promoted changes to target system.
Steps to Deploy objects:
1. Select the Deploy radio button on the Environment Promotion Actions screen
and click Next. The Select Source data location screen is displayed. Click
Browse to select the zip file that was created in the Promote process (see
Figure 3.30)

Figure 3.30: Select Source Location

2. Click Next. This displays the Select Target Directory screen. Click Browse to
select the target system on which the promoted zip is to be deployed (see
Figure 3.31).

Adeptia Migration Utility User Guide 31

 Figure 3.31: Select Target System Install Directory
3. Click Next. This displays a screen, where you need to enter your name in the
specified field. This is just to keep track of who deployed the objects (see
Figure 3.32).

Figure 3.32: Enter username

4. Click Next. This displays the View Deployed Logs screen (see Figure 3.33).

Adeptia Migration Utility User Guide 32

 Figure 3.33: View Deployed Logs
This screen displays all logs and confirms whether the deployment operation is successful or
not. If it is successful, a message stating, “Deployment of selected objects completed
successfully” is displayed in the View Deployed Logs screen and as a popup window, and the
selected objects are deployed. Incase of failure, it displays an error message in the View
Deployed Logs screen and as a popup window, and rollbacks the entire operation.
5. Click Finish to complete the deploy process and exit the Migration utility.

Adeptia Migration Utility User Guide 33

4 MIGRATION
You can use the Migration process to migrate objects from the currently installed version to a
new upgraded version. This process also allows you to take a backup of all objects and
configuration files from the current installation and restore them whenever required.
For example, you are currently using Adeptia Server 4.4 on your system. With the release of
Adeptia Server 4.5, you want to upgrade to this new version. After installing it, you need to
transfer all data from Adeptia Server 4.4 to Adeptia Server 4.5. To do this, you can use the
Migration process.

You can use the Migration process to insert objects from the source
database to the target database. However, you cannot update the
objects in the target database.

Steps to migrate objects using Migration

1. Select the Migration radio button on the Select Action screen and click Next.
This displays the Migration actions screen (see Figure 4.1).

Figure 4.1: Migration Actions

This screen displays the migration actions, which are outlined in the table below.

Table 4.1: Migration Actions

Action Description

Online Migration Allows you to migrate objects from the source

system database to the target system
database. The source and target databases

Adeptia Migration Utility User Guide 34

 should be in running mode when using this
action.
Offline Migration Allows you to create a zip file containing all
source objects and configuration files. This zip
file is henceforth used for Export/Import,
Backup/Restore of the source objects and files.

ONLINE MIGRATION

Online Migration can be run on any desktop. It facilitates you to migrate objects from the
source database to the target database. Both these databases need to be connected for this
process. For example, if the earlier version of Adeptia Server is on HSQL database, and the
upgraded version is on SQL Server, you can use this process to transfer the objects.
Steps to migrate objects using online migration:
2. Select Online migration radio button on the Migration Actions screen and click
Next. The Configuration Settings screen for Source Database is displayed (see
Figure 4.2).

Figure 4.2: Configuration Settings for Source Database

3. Select the source database type from the Database Type drop-down menu.
4. Enter the name of the source database server in the Server Name field.
5. Enter the port number of the source database in the Port No. field.
6. Enter the name of the source database in the Database Name field.

Adeptia Migration Utility User Guide 35

 7. Enter the username and password for accessing the source database, in the
UserName and Password fields respectively.
8. Click Next. This displays the Configuration Settings screen for the Target
Database (see Figure 4.3).

Figure 4.3: Configuration Settings for Target Database

Refer to Appendix A for sample configuration values for SQL Server and
HSQL databases.

9. Enter the target database information and click Next. The Select Objects
screen is displayed (see Figure 4.4). This screen displays a list of all the tables
of the Adeptia Server.

Adeptia Migration Utility User Guide 36

 Figure 4.4: Select Tables
10. Check the checkbox(s) against the tables that you want to migrate.

You can select one or more tables.

All tables that are prefixed with ABPM are quartz tables. These tables and the
dt_properties tables and are listed in case of the SQL Server database only. It is
recommended not to migrate these tables, as the migration process is likely to fail in
such a case, as all tables in the source and target databases should be the same.
Similarly, please migrate the log tables (AU_Log and AU_TransactionData), only if you
need the log, as these are big size tables and slow down the migration process
considerably.

You need to be careful while migrating tables, as if an error occurs, it

cannot be undone. Additionally, if the migration process fails, you have
to rollback the entire operation.

11. Click Next. This displays the View Logs screen (see Figure 4.5).

Adeptia Migration Utility User Guide 37

 Figure 4.5: View Logs
This screen displays all logs and confirms whether the export operation is successful or not. If
it is successful, a message stating, “Selected tables exported successfully” is displayed in the
View Logs screen and as a popup window. Incase of failure, it displays an error message in the
View Logs screen and as a popup window, and rollbacks the entire operation.
12. Click Finish. This completes the migration process.

When you migrate to an upgraded version, the Migration tool takes

care of all the new fields at the target end, and inserts default values
for these fields. These values are displayed in the View Logs screen.
Refer to Appendix A for more details on the default values. To change
these values, you need to manually update them using the Manage
section in the Adeptia Server.

OFF LINE MIGRATION

The Offline Migration process is used for migrating objects when the source database to target
database, when the databases are not connected at the same time. It is used to migrate
objects as well as take backup.
Steps to migrate objects using offline migration
1. Select Offline migration radio button on the Migration Actions screen and click
Next. This displays the Offline actions screen (see Figure 4.6).

Adeptia Migration Utility User Guide 38

 Figure 4.6: Offline Actions screen
This screen displays the Off Line migration actions, which are outlined in the table below.
Table 4.2: Offline Actions
Action Description

Export/Backup Creates a zip file containing all source

database objects and configuration files.
Import/Restore Import all source database objects and
configuration files from the zip file to the target
system.

EXPORT/BACKUP
Steps for offline migration (Export/Backup):

1. Select Export/Backup radio button on the Offline Actions screen and click
Next. This displays the Select Source Database screen. Click Browse to select
the source system where the Adeptia Server is installed. (see Figure 4.7).

Adeptia Migration Utility User Guide 39

 Figure 4.7: Select Source System
2. Click Next. The Select Target Location screen is displayed. Click Browse to
select the target location where the exported zip file will be saved (see Figure
4.8).

Figure 4.8: Select Target Location

3. Click Next. This displays the View Backup Logs screen (see Figure 4.9).

Adeptia Migration Utility User Guide 40

 Figure 4.9: View Backup Logs
This screen displays all logs and confirms whether the export operation is successful or
not. If it is successful, a message stating “Backup completed successfully” is displayed in
the View Backup Logs screen and as a window popup, and a zip file is created. In case of
failure, it displays an error message in the View Backup Logs screen and as a window
popup, and rollbacks the entire operation.

IMPORT/RESTORE

Steps for offline migration (Import/Restore):

1. Select Import/Retain radio button on the Offline Actions screen and click Next.
This displays the Import actions screen (see Figure 4.10).

Adeptia Migration Utility User Guide 41

 Figure 4.10: Import Actions screen
This screen displays the Import migration actions, which are outlined in the table below.
Table 4.3: Import Actions
Action Description

All Includes Database object and configuration

file. It is used for migrating objects in the
same version only.
Only Database Includes Database objects only
Only Configuration File Includes configuration files only

2. Select the All radio button, when both the source and target databases have
the same version of the Adeptia Server. For example, when migrating objects
from Adeptia Server 4.5 to Adeptia Server 4.5, click this option.
3. Select the Only Database radio button, when the source and target databases
have different versions of the Adeptia Server. For example, when migrating
objects from Adeptia Server 4.4 to Adeptia Server 4.5, click this option. This
displays the Select Source location screen. Click Browse to select the zip file
created in the Export process (see Figure 4.11).

Adeptia Migration Utility User Guide 42

 Figure 4.11: Select Source Location
4. Click Next. The Select Target Location screen is displayed. Click Browse to
select the directory, where the target system of the Adeptia Server is installed
(see Figure 4.12).

Figure 4.12: Select Target System Install Directory

5. Click Next. The Select Objects screen is displayed (see Figure 4.13). This
screen displays a list of all the tables of the Adeptia Server.

Adeptia Migration Utility User Guide 43

 Figure 4.13: Select Objects screen
6. Check the checkbox(s) against the objects that you want to restore.

You can select one or more objects.

All objects that are prefixed with ABPM are quartz tables. These tables and the
dt_properties objects are listed in case of the SQL Server database. It is recommended
not to restore these objects as the migration process is likely to fail in such a case, as all
tables in the source and target databases should be the same. If they are different then
deselect the log objects such as (AU_Log and AU_TransactionData) as it slows down the
migration process.

You need to be careful while migrating objects, as if an error occurs, it

cannot be undone. Additionally, if the migration process fails, you have
to rollback the entire operation.

7. Click Next. This displays the View Restore Logs screen (see Figure 4.14).

Adeptia Migration Utility User Guide 44

 Figure 4.14: View Restore Logs
This screen displays all logs and confirms whether the import operation is successful or not. If
it is successful, a message stating, “Selected database tables restored successfully” is
displayed in the View Restore Logs screen and as a popup window. Incase of failure, it displays
an error message in the View Restore Logs screen and as a popup window, and rollbacks the
entire operation.

8. Select the Only Configuration Files radio button on the Import Actions screen,
when you want to restore the configuration files only. This displays the Select
Source location screen (refer to Figure 4.11).
9. Click Browse to select the zip file created in the Export process.
10. Click Next. The Select Target Location screen is displayed (refer to Figure
4.12).
11. Click Browse to select the directory, where the target system of the Adeptia
Server is installed.
12. Click Next. The Select Configuration Files screen is displayed (see Figure
4.15). This screen displays a list of all the configuration files for all objects of
the Adeptia Server.

Adeptia Migration Utility User Guide 45

 Figure 4.15: Select Configuration Files
13. Check the checkbox(s) against the files that you want to restore.

You can select one or more files.

14. Click Next. This displays the View Logs screen (see Figure 2.15).

Figure 4.16: View Logs

This screen displays all logs and confirms whether the import operation is successful or not. If
it is successful, a message stating, “Selected configuration files restored successfully” is
displayed in the View Logs screen and as a popup window. Incase of failure, it displays an

Adeptia Migration Utility User Guide 46

error message in the View Logs screen and as a popup window, and rollbacks the entire
operation.
Once the migration process is complete, you can start the Adeptia Server 4.5.

Before starting Adeptia Server 4.5, it is advised to manually compare

server-configuration properties and server-configuration-bak properties
files to check the selected configuration parameters.
Please ensure that the password has been changed to indigo1.

Adeptia Migration Utility User Guide 47

5 PATCH UPDATE
For Adeptia Server, patches are released from time to time to update the existing installation.
Patch is basically a ZIP file which contains changed file and SQL script to change the backend
database. Patch update option of the migration utility is used to update the patch on the
existing installation. When a patch is applied, it replaces the changed file and changes the
backend database. You can also remove the patch, which you have applied.

Before applying patch, make sure that the Kernel and Web Runner are
stopped. Once you have finished the process, you need to start the
Kernel and the Web Runner.

Steps to transfer objects using Patch Update

1. Select the Patch Update radio button on the Select Action screen and click
Next. This displays the Patch Update actions screen (see Figure 5.1).

Figure 5.1: Patch Update Actions

This screen displays the patch update actions, which are outlined in the table below.

Table 5.1: Patch Update Actions

Action Description

Apply Patch Allows you to transfer objects from one service

pack to another.
Remove Patch Allows you to rollback the Apply Patch process
and replace all database files with the older

Adeptia Migration Utility User Guide 48

 version.

You can run the Patch Update process on SQL Server only.

APPLY PATCH

Apply patch allows you to apply the patch on currently installed Adeptia Server.

Steps to transfer objects using Apply Patch:

1. Select Apply Patch radio button on the Patch Update Actions screen and click
Next. The Select Patch File Location screen is displayed. Click Browse to the
select the directory where the patch file (zip file containing all the changes) is
saved (see Figure 5.2).

Figure 5.2: Saved Patch File

2. Click Next. This displays the Select Target Directory screen. Click Browse to
select the target system on which you want to save the patch file (see Figure
5.3).

Adeptia Migration Utility User Guide 49

 Figure 5.3: Select Target System
3. Click Next. This displays the apply patch process in running state (see Figure
5.4).

Figure 5.4: Apply Patch Process

4. Once all validations are performed and process is complete, a popup window is
displayed asking whether you want to create a recovery file for the patch. You
require this file if you want to rollback the apply patch action (see Figure 5.5).

Figure 5.5: Generate Recovery File Popup

5. Click Yes to create a recovery file. This displays the Save Recovery File screen
(see Figure 5.6). If you click No, then the View Apply Patch Logs screen is
displayed.

Adeptia Migration Utility User Guide 50

 Figure 5.6: Enter Recovery File Name
6. Select the directory where you want to save the recovery file and enter the
name of the recovery file in the File name field.

The Recovery File is also created as a zip file. Recovery file keeps the
backup of existing files, which will be replaced by patch update.

7. Click Save. This displays the View Apply Patch Logs screen (see Figure 5.7).

Adeptia Migration Utility User Guide 51

 Figure 5.7: View Apply Patch Logs
This screen displays all logs and confirms whether the Apply Patch process is successful or not.
If it is successful, a message stating, “Apply Patch of selected objects completed successfully”
is displayed in the View Apply Patch Logs screen and as a popup window, and the selected
objects are updated to the service pack. In case of failure, it displays an error message in the
View Apply Patch Logs screen and as a popup window, and rollbacks the entire operation.
8. Click Finish to complete the Apply Patch process and exit the Migration utility.

REMOVE PATCH

Remove Patch allows you to rollback the changes done by patch update. When you apply a
patch, it asks you to create a recovery file. If you have created a recovery file, you can
remove the patch, which you have applied. When you remove a patch, migration utility asks
you to select the recovery file, which you have created during patch update process and then
roll back all the changes done by patch update. It also rolls back the changes done in the
backend database.
Steps to revert objects using Remove Patch:
1. Select Remove Patch radio button on the Patch Update Actions screen and
click Next. The Select Recovery Patch File Location screen is displayed. Click
Browse to the select the directory where the recovery patch file (zip file) is
saved (see Figure 5.8).

Adeptia Migration Utility User Guide 52

 Figure 5.8: Saved Recovery Patch File
2. Click Next. This displays the Select Target Directory screen. Click Browse to
select the target system on which you want to save the recovered patch file
(see Figure 5.9).

Figure 5.9: Select Target System

3. Click Next. This displays the View Remove Patch Logs screen (see Figure
5.10).

Adeptia Migration Utility User Guide 53

 Figure 5.10: View Remove Patch Logs
This screen displays all logs and confirms whether the Remove Patch process is successful or
not. If it is successful, a message stating, “Remove Patch of selected objects completed
successfully” is displayed in the View Remove Patch Logs screen and as a popup window, and
the selected objects are updated to the service pack. In case of failure, it displays an error
message in the View Remove Patch Logs screen and as a popup window, and rollbacks the
entire operation.
4. Click Finish to complete the Remove Patch process and exit the Migration
utility.

Adeptia Migration Utility User Guide 54

6 APPENDIX A

SAMPLE CONFIGURATION VALUES

SQL SERVER DATABASE

Table 6.1: Sample Configuration Values for SQL Server Database

Field Sample Value

Server Name IP Address or Machine name

Port No.: 1433 (Default Value)
Database Name Name of the database
UserName Name of the user
Password Password

HSQLDB DATABASE

Table 6.2: Sample Configuration Values for HSQL Database

Field Sample Value

Server Name Machine name

Port No.: 2476 for BPM Objects (Default Value)
2477 for BPM Logs (Default Value)
Database Name 2476: Blank
2477: Blank
UserName 2476: sa
2477: sa
Password 2476: Blank
2477: sa

DEFAULT VALUES FOR ADDITIONAL COLUMNS IN AN UPGRADED VERSION

Adeptia Migration Utility User Guide 55

 Table 6.3: Default Values for Additional Columns in an Upgraded Version
Field Type Default Value

NOT NULL Numeric: 0

Text: Empty String
Boolean: False
NULL Database specific NULL

Adeptia Migration Utility User Guide 56

7 TABLE OF FIGURES
Figure 2.1: Adeptia Migration Utility screen ..................................................................... 6
Figure 2.2: Select Action screen .................................................................................... 6
Figure 3.1: Environment Promotion Actions screen ........................................................... 7
Figure 3.2: Select Source System Install Directory ........................................................... 8
Figure 3.3: Select Group .............................................................................................. 9
Figure 3.4: Select the Action ......................................................................................... 9
Figure 3.5: Select Process Flows .................................................................................. 10
Figure 3.6: Select Service........................................................................................... 11
Figure 3.7: Select Target Directory .............................................................................. 12
Figure 3.8: View Export Logs ...................................................................................... 12
Figure 3.9: Select Source Location ............................................................................... 13
Figure 3.10: Select Target System Install Directory ........................................................ 14
Figure 3.11: Select Group........................................................................................... 14
Figure 3.12: Generating Compare Selected Objects Process............................................. 15
Figure 3.13: Compare Objects (Process Flow Objects)..................................................... 15
Figure 3.14: Compare Objects (All Objects)................................................................... 16
Figure 3.15: Select View Changes option ...................................................................... 17
Figure 3.16: View Difference ....................................................................................... 18
Figure 3.17: Select Retain XML Location ....................................................................... 19
Figure 3.18: Enter username....................................................................................... 19
Figure 3.19: Select Target Location for Promoted Objects................................................ 20
Figure 3.20: View Promoted Logs................................................................................. 20
Figure 3.21: View PDF Report...................................................................................... 21
Figure 3.22: Generate Retain List Process ..................................................................... 22
Figure 3.23: Retain List .............................................................................................. 22
Figure 3.24: Select Specific Activity Option ................................................................... 24
Figure 3.25: Retain Activity Query Builder..................................................................... 25
Figure 3.26: Activity Name Displayed in the Query Information Field................................. 26
Figure 3.27: Fields associated with a Service ................................................................. 27
Figure 3.28: Select Field............................................................................................. 28
Figure 3.29: Select Delete Option ................................................................................ 30
Figure 3.30: Select Source Location ............................................................................. 31

Adeptia Migration Utility User Guide 57

Figure 3.31: Select Target System Install Directory ........................................................ 32
Figure 3.32: Enter username....................................................................................... 32
Figure 3.33: View Deployed Logs ................................................................................. 33
Figure 4.1: Migration Actions ...................................................................................... 34
Figure 4.2: Configuration Settings for Source Database................................................... 35
Figure 4.3: Configuration Settings for Target Database ................................................... 36
Figure 4.4: Select Tables ............................................................................................ 37
Figure 4.5: View Logs ................................................................................................ 38
Figure 4.6: Offline Actions screen ................................................................................ 39
Figure 4.7: Select Source System ................................................................................ 40
Figure 4.8: Select Target Location................................................................................ 40
Figure 4.9: View Backup Logs ..................................................................................... 41
Figure 4.10: Import Actions screen .............................................................................. 42
Figure 4.11: Select Source Location ............................................................................. 43
Figure 4.12: Select Target System Install Directory ........................................................ 43
Figure 4.13: Select Objects screen ............................................................................... 44
Figure 4.14: View Restore Logs ................................................................................... 45
Figure 4.15: Select Configuration Files.......................................................................... 46
Figure 4.16: View Logs............................................................................................... 46
Figure 5.1: Patch Update Actions ................................................................................. 48
Figure 5.2: Saved Patch File........................................................................................ 49
Figure 5.3: Select Target System................................................................................. 50
Figure 5.4: Apply Patch Process................................................................................... 50
Figure 5.5: Generate Recovery File Popup ..................................................................... 50
Figure 5.6: Enter Recovery File Name........................................................................... 51
Figure 5.7: View Apply Patch Logs ............................................................................... 52
Figure 5.8: Saved Recovery Patch File .......................................................................... 53
Figure 5.9: Select Target System................................................................................. 53
Figure 5.10: View Remove Patch Logs .......................................................................... 54

Adeptia Migration Utility User Guide 58

8 TABLE OF TABLES
Table 3.1: Environment Promotion Actions ...................................................................... 8
Table 3.2: Services and their name which have changed ................................................. 11
Table 3.3: Legends on the Compare Objects screen........................................................ 16
Table 4.1: Migration Actions........................................................................................ 34
Table 4.2: Offline Actions ........................................................................................... 39
Table 4.3: Import Actions ........................................................................................... 42
Table 5.1: Patch Update Actions .................................................................................. 48
Table 6.1: Sample Configuration Values for SQL Server Database..................................... 55
Table 6.2: Sample Configuration Values for HSQL Database............................................. 55
Table 6.3: Default Values for Additional Columns in an Upgraded Version .......................... 56

Adeptia Migration Utility User Guide 59