3Migrating Configuration Data Using the Graphical User Interface

Migrating Configuration Data Using the Graphical User Interface

This chapter describes how to migrate configuration data directly from one environment to another environment using the graphical user interface (GUI) of the Oracle Migration Tool On Demand client. It contains the following topics:

About the Graphical User Interface

You can use the GUI of the Oracle Migration Tool On Demand client to migrate configuration data directly from one environment (the source environment) to another environment (the target environment) without the need to construct and run commands. You can use the GUI to migrate all of the customized configuration data for all of the features that are supported by the Oracle Migration Tool On Demand client, or to migrate the configuration data for certain features only. You cannot use the GUI to migrate a subset of the configuration data for a feature. If a feature that you select for migration has a dependency on configuration data for one or more features that are not selected for the migration, then you are prompted to select those features also for migration. If you choose not to migrate the configuration data for a feature on which a selected feature is dependent, then the selected feature might not be migrated correctly.

If you want to migrate the configuration data for all of the supported features, or all of the configuration data for one or more features, and you do not want to make any changes to the configuration data, then it is recommended that you use the GUI of the Oracle Migration Tool On Demand client. However, you must use the command-line interface if you want to perform any of the following tasks:

Download your configuration data and make changes to it before you upload it to another environment.
Download and upload a subset of the configuration data for a feature, for example, if you want to migrate a single access profile or the search layouts for a single record type.

In the GUI of the Oracle Migration Tool On Demand client, the services for migrating the configuration data for the features are grouped into four categories, as follows:

Company Administration. This category includes the services for migrating the configuration data for the following features:
- Assessment Scripts (that is, sales assessment templates)
- Report Folders (that is, role association for Analytics folders)
- Sales Category
- Sales Process
- Sales Stage
User Management and Access Controls. This category includes the services for migrating the configuration data for access profiles and roles.
Application Customization. This category includes the services for migrating the configuration data for the application customization features that are supported by the Oracle Migration Tool On Demand client, for example, page layouts, customized record types, custom Web applets and tabs, client side extensions, and so on.
Business Process Management. This category includes the services for migrating the configuration data for the assignment manager, modification tracking, integration event queue, lead conversion mappings, process administration and process administration transition states, and workflow features.

For each service that you select, the Oracle Migration Tool On Demand client does the following:

Runs a ReadAll command and downloads the output XML files to the appropriate directory on your computer.
Runs an Upsert command for each of the XML files that were downloaded by the ReadAll command.

The order in which the services are run is determined by the dependencies between the features. After the ReadAll command for a feature completes successfully, the Upsert command is run as many times as necessary to process the XML files that were generated by the ReadAll command. If you select the Use more resources check box when you set up the migration job, then multiple services will be processed concurrently, and the job will run more quickly.

The Oracle Migration Tool On Demand client places the output from the ReadAll commands in the directory that is selected for the output files when the migration job is set up.

Migrating the Configuration Data

This topic describes how to migrate customized configuration data using the GUI of the Oracle Migration Tool On Demand client.

Before you start to migrate the configuration data for some or all features, note the following considerations:

To migrate the configuration data for a feature, your user role must have the necessary privileges. For more information about the privileges required, see Privileges for Administrators.
Some features are dependent on other features and cannot be migrated correctly unless the features on which they are dependent are also migrated. For more information about the dependencies, see Migration Dependencies.
The length of time that a migration job takes depends on the amount and complexity of the configuration data that you are migrating. A typical migration job in which all of the supported features are migrated takes around one hour, but your migration job might take more, or less time.
The Oracle Migration Tool On Demand client places the output from the ReadAll commands in the directory that you select for the output files when you set up the migration job. The naming conventions for the subdirectories and files are the same as the naming conventions that are used for the output files that are generated when the Read and ReadAll commands are run in the command-line interface. For more information, see Location of Output XML Files for Read and ReadAll Commands.
If a pre-existing file in an output directory has the same name as a file that is generated when you migrate the data, then the pre-existing file is overwritten.
If your target environment already contains configuration data, then it is recommended that you back up that data before you run the migration job. You must use the command-line interface to back up the data, as described in the following procedure.

Caution: Most components of Oracle CRM On Demand cannot revert to their original states by using the backup copies of the configuration data. For example, after a new access profile is inserted into the target environment, it cannot be removed by using the backup copy (that is, access profiles in Oracle CRM On Demand cannot be deleted). A backup copy of the configuration data provides a reference of the target environment before applying new configuration data.

The following procedure describes how to back up the configuration data from the target environment.

To back up the configuration data from the target environment

Start the command-line interface of the Oracle Migration Tool On Demand client, as described in Starting the Oracle Migration Tool On Demand Client Command-Line Interface.

Back up the existing configuration data in the target environment by running the appropriate commands for the configuration data that you want to migrate, as follows:

migrationtool -u UserID -s TargetServer ReadAll AccessProfile 
migrationtool -u UserID -s TargetServer ReadAll ActionBarCustomWebApplet
migrationtool -u UserID -s TargetServer ReadAll ActionBarLayout
migrationtool -u UserID -s TargetServer ReadAll AssignmentRule
migrationtool -u UserID -s TargetServer ReadAll AssignmentRuleGroup
migrationtool -u UserID -s TargetServer ReadAll CascadingPicklist
migrationtool -u UserID -s TargetServer ReadAll ClientSideExtension
migrationtool -u UserID -s TargetServer ReadAll ConcatenatedField
migrationtool -u UserID -s TargetServer ReadForValue CustomHTMLHeadTag
migrationtool -u UserID -s TargetServer ReadAll CustomRecordType
migrationtool -u UserID -s TargetServer ReadAll CustomWebLink
migrationtool -u UserID -s TargetServer ReadAll CustomWebTab 
migrationtool -u UserID -s TargetServer ReadAll DetailPageCustomWebApplet
migrationtool -u UserID -s TargetServer ReadAll DynamicLayout
migrationtool -u UserID -s TargetServer ReadAll EnableModificationTracking
migrationtool -u UserID -s TargetServer ReadAll FieldAuditSetUp
migrationtool -u UserID -s TargetServer ReadAll FieldManagement
migrationtool -u UserID -s TargetServer ReadAll HomePageCustomWebApplet
migrationtool -u UserID -s TargetServer ReadAll HomepageLayout
migrationtool -u UserID -s TargetServer ReadAll HomeTabCustomWebApplet
migrationtool -u UserID -s TargetServer ReadAll IntegrationEventQueue
migrationtool -u UserID -s TargetServer ReadAll LeadConversionMapping
migrationtool -u UserID -s TargetServer ReadAll ListAccessAndOrder
migrationtool -u UserID -s TargetServer ReadAll PageLayoutField
migrationtool -u UserID -s TargetServer ReadAll PageLayoutRelatedInformation
migrationtool -u UserID -s TargetServer ReadAll PageLayoutSection 
migrationtool -u UserID -s TargetServer ReadAll Picklist 
migrationtool -u UserID -s TargetServer ReadAll PicklistValueGroup
migrationtool -u UserID -s TargetServer ReadAll ProcessAdministration
migrationtool -u UserID -s TargetServer ReadAll ProcessAdministrationTransitionState
migrationtool -u UserID -s TargetServer ReadAll RelatedInformationLayout
migrationtool -u UserID -s TargetServer ReadAll ReportFolder
migrationtool -u UserID -s TargetServer ReadAll Role
migrationtool -u UserID -s TargetServer ReadAll SalesAssessmentTemplate
migrationtool -u UserID -s TargetServer ReadAll SalesCategory
migrationtool -u UserID -s TargetServer ReadAll SalesProcess
migrationtool -u UserID -s TargetServer ReadAll SalesStage
migrationtool -u UserID -s TargetServer ReadAll SearchLayout
migrationtool -u UserID -s TargetServer ReadAll WorkflowRuleSet

where:

UserID is your user sign-in ID for the Oracle CRM On Demand target environment where the extraction occurs.
TargetServer is the URL for the Oracle CRM On Demand server for the target environment.

In addition:

If you want to back up the workflow action sets for each of the record types and trigger events that exist on the target environment, then run the following command:
```
migrationtool -u UserID -s TargetServer ReadForRuleSet WorkflowActionSet RecordType TriggerEvent [ParentRecordType]
```
For more details on extracting workflow action sets, see Extracting a Workflow Action or a Workflow Action Set.
If you want to back up all workflow user sets that exist on the target environment, then run the following command:
```
migrationtool -u UserID -s TargetServer ReadForRuleSet WorkflowUserSet Analytics ScheduledEvent
```
For more details on extracting workflow user sets, see Extracting Workflow User Sets.

For information about where the XML files that are created by the commands are stored, see Location of Output XML Files for Read and ReadAll Commands.

The following procedure describes how to migrate the customized configuration data from a source environment to a target environment using the GUI of the Oracle Migration Tool On Demand client.

To migrate the configuration data

Start the GUI of the Oracle Migration Tool On Demand client, as described in Starting the Oracle Migration Tool On Demand Client Graphical User Interface.
In the Login tab of the GUI, in the Source Environment Details section, enter the URL for the server from which you want to download the configuration data, that is, the server for the source environment.
Enter your user name and password for the source environment.
In the Target Environment Details section, enter the URL for the server to which you want to upload the configuration data, that is, the server for the target environment.
If your user name and password are the same for both the source environment and the target environment, then select the Copy login details to Target check box. Otherwise, enter your user name and password for the target environment.
Click Next.
In the Services tab, deselect the check box for the service for any feature that you do not want to migrate.
By default, all services in all categories are selected, and the customized configuration data for all of the supported features will be migrated unless you deselect one or more services. You can deselect individual services, or an entire category of services, as follows:
- To deselect all of the services in a category, deselect the check box at the category level.
- To deselect a specific service, expand the relevant category and deselect the check box for the service. For example, to deselect the services for migrating access profiles and roles, deselect the check box for the User Management and Access Controls category.
In the Settings tab, do the following:
- If you access the Internet using a proxy server, then in the Proxy Settings section, enter the URL, user ID and password, and (optionally) a port number for the Internet proxy server.
  
  Note: If you do not specify a port number, then port 80 is used by default.
- (Optional) If you want the output XML files or the log files to be placed in a directory other than the default directory, then in the Directory Settings section, specify the directory path or browse to a directory and then select it.
  The path to the default directory for the output XML files is:
  - On a computer using a Windows operating system:
```
Installation_directory\windows\Oracle_Migration_Tool_On_Demand\app\repository
```
  - On a computer using any operating system other than a Windows operating system:
```
Installation_directory/other/UIMigrationTool/repository
```
  The path to the default directory for the log files is:
  - On a computer using a Windows operating system:
    Installation_directory\windows\Oracle_Migration_Tool_On_Demand\app\log
  - On a computer using any operating system other than a Windows operating system:
    Installation_directory/other/UIMigrationTool/log
  In the directory path, Installation_Directory is the name of the directory where the Oracle Migration Tool On Demand client is installed.
  
  Note: If you choose a directory other than the default directory for the XML output files, then make sure that you do not overwrite the output XML files that were created when you backed up the configuration data from the target environment.
- (Optional) If you want to allocate additional CPU resources on your computer to the migration job, then in the Advanced Settings section, select the Use more resources check box.
  If you select the Use more resources check box, then the Oracle Migration Tool On Demand client uses more of the CPU resources on your computer to process multiple services concurrently, and the migration job will run more quickly.
When you finish setting up the migration job and are ready to run the job, click Finish in any one of the Login, Services, or Settings tabs.
If a feature that is selected for migration has a dependency on one or more features that are not selected for migration, then you are prompted to choose whether you want to migrate the configuration data for those features also. Otherwise, the migration tool starts to run the services to migrate the selected features.
If you are prompted to choose whether you also want to migrate the configuration data for the features on which one or more of the selected features depend, then do one of the following:
- If you want to migrate the configuration data for the features on which one or more of the selected features depend, then click Yes.
- If you do not want to migrate the configuration data for the features on which one or more of the selected features depend, then click No.
  
  Note: If you choose not to migrate a feature on which a selected feature is dependent, then the selected feature might not be migrated correctly.
The migration tool starts to run the services to migrate the configuration data.

You can monitor the progress of the migration job in the Progess tab of the GUI, see Monitoring the Progress of the Migration Job.

Caution: If you close the GUI while a migration job is running, the job is canceled. When a job is canceled, the Oracle Migration Tool On Demand client does not roll back any of the services that have already been run, and any configuration data that has already been uploaded to the target environment is not removed or rolled back. As a result, the configuration data in the target environment might be incomplete, or inconsistent, or both.

Monitoring the Progress of the Migration Job

After you click Finish in the Oracle CRM On Demand Migration Tool GUI, you can monitor the progress of the migration job in the Progress tab of the GUI.

In the Progress tab, a status bar shows the percentage complete while the job is running. The status of the service for each feature is shown while the service is running and continues to be shown after the service completes. The order in which the services are run is determined by the dependencies between the features. After the ReadAll command for a given feature completes successfully, the Upsert command is run as many times as necessary to process the XML files that were generated by the ReadAll command. If the ReadAll command for a feature fails, then the Upsert command is skipped (that is, the command is not run) for that feature.

When all of the services have completed, a check mark is shown and the overall status for the job changes to Done. If any errors occurred, review the log file for the job to help you to determine what caused the error.

Canceling a Migration Job

You can cancel a migration job that is running in the GUI of the Oracle Migration Tool On Demand client.

Caution: When you cancel a migration job, the Oracle Migration Tool On Demand client does not roll back any of the services that have already been run, and any configuration data that has already been uploaded to the target environment is not removed or rolled back. As a result, the configuration data in the target environment might be incomplete, or inconsistent, or both.

To cancel a migration job

In any tab of the GUI, click Cancel.