Migrating an application or product by using the productMigration command-line tool

Use the productMigration.bat or productMigration.sh command-line tool to migrate an application or a product, manage target systems, view migration status, and download logs. Specify parameters in the command line, in the migration.properties file, or in both.

Command line help

The help option on the command line lists all the available actions, and the arguments for each action. You can invoke the utility with "help" as the argument. For example:

./productMigration.sh help

Mandatory parameters

To invoke any of the actions (except help), set following parameters to configure the system against which the tool runs the specified action.

Note: Do not use "localhost" as the host name in a node URL. Using "localhost" causes the product migration to fail.
Parameters in the migration.properties file Command line argument Description
node.endpointurl -url The SOAP servlet URL against which the specified action is run.
node.username -user The user ID available for the url, with appropriate required privileges.
node.password -pwd Password for the user.

The target action can be specified directly and is not a named argument. For example:

./productMigration.sh <ACTION> –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install [Options]

The command-line tool actions are grouped into the following categories:

Manage target systems

Use the parameters in this category to manage target system instances ( Data-Admin-System-Targets class).

Parameters in the migration.properties file Command line argument Description
target.targname -targname A short descriptive name for the target.
target.URL -targurl The URL for the target system. Either cut and paste the URL into this field, or enter the entire URL of the target system in the format http://hostname:port/context/serveletname

The system ignores the serveletname.
target.username -targUser An operator name of the target system, which has import privileges.
target.password -targPwd Password of the specified operator.

addTarget action

Adds a migration target to the source system. Unlike migration from the user interface that allows you to specify the target for dynamic migration, the command-line tool requires a target to be added before a migration request is initiated against it. A target is identified by its host name. You cannot add two targets with the same host name. If a target already exists, the same target is overwritten with the new details provided.

Example

./productMigration.sh addTarget –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –https false –host wponnsw7 –port 8080 –context prweb –targUser ponns –targPwd rules

editTarget action

Enables the changing of an already defined target. The target to be edited is identified by the host name. If the target does not exist, an appropriate message is returned, without the addition of a new target.

Example

./productMigration.sh editTarget –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –host wponnsw7 –port 8181 –context prweb1 –https false –targUser ponns –targPwd rules
This changes the target wponnsw7’s port and context root, leaving the remaining parameters as they are.

deleteTarget action

Deletes the target from the host system as identified by the host name supplied. If the target is not found in the source, an appropriate message is returned.

Example

./productMigration.sh deleteTarget –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –host wponnsw7

showTargets action

Lists all the targets available in the host system. No other arguments are required. Optionally, you can specify a target host, and the details of only that host are returned.

Example

The following example lists all the targets added in the host.

./productMigration.sh showTargets –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install

The following example below returns only the details of target wponnsw7 if present, otherwise an appropriate message is returned.

./productMigration.sh showTargets –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –host wponnsw7

View products

Use the parameters in this category to view the products available for migration.

showProducts action

Lists all the products accessible to the user specified.

Example

./productMigration.sh showProducts –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install

Migrate products

Use the parameters in these categories to migrate the specified products.

Parameters in the migration.properties file

  • migrate.target.targname.<INDEX>: Host name of the target system. The index must be a number, and must be incremented to specify multiple targets.
  • migrate.product.<INDEX>: The products to be migrated. Products must be in the format productName:productVersion:productPatch. To specify multiple products, increment the index. The index determines the import order.
  • download.only: To download the product without importing, set download.only=true.

Command line arguments

-targets The destination of the migration. Multiple targets can be specified as a comma-separated list.
-products Products to be migrated. Multiple products must be comma-separated, for example, "prodName1:prodVersion1:prodPatch1,prodName2:prodVersion2:prodPatch3".
- downloadOnly Downloads the product without importing.

migrate action

Migrates the specified products to the specified targets from the source. You must define both the products and targets before invoking this action. You must specify at least one target and one product.

Example

./productMigration.sh migrate –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –targets serverName1,serverName2 –products sample:01-01-01,test:01-01-01

To use the properties file in addition to the mandatory parameters, specify the hosts and products like this:

migrate.target.host_1= serverName1
migrate.target.host_2= serverName2
migrate.product_1=sample:01-01-01
migrate.product_2=test:01-01-01-01

In this case, sample:01-01-01 is imported first, followed by test:01-01-01.

Optional. Download only

To download the product without importing, set the download.only parameter in the Config Parameters common for "migrate" and "migrateApp" action section.

Example

download.only=true

Migrate applications

Use the parameters in these categories to migrate the specified applications.

Parameters in the migration.properties file

  • migrateapp.target.targname.<INDEX>: Host name of the target system. The index must be a number and must be incremented to specify multiple targets.
  • migrateapp.product.<INDEX>: The applications to be migrated. Applications must be in the formatApplicationName!ApplicationVersion!AccessGroup1!AccessGroup2. To specify multiple applications, increment the index. The index determines the import order. Access Groups provided as part of appDetails will be updated with highest Application version at the target. If no Access Groups are provided, all the Access Groups in the target referring the application migrated will be updated with the latest Application version.

    If ApplicationVersion is empty, the highest version of that Application is migrated.

  • download.only: To download the product without importing, set download.only=true.

Command line arguments

-targNames The destination of the migration. Multiple targets can be specified as a comma-separated list.
-appDetails Applications to be migrated. Multiple applications must be comma-separated, for example, "prodName1:prodVersion1:prodPatch1,prodName2:prodVersion2:prodPatch3".
-downloadOnly Downloads the application without importing.

migrate application action

Migrates the specified applications to the specified targets. You must define both the applications and targets before invoking this action. You must specify at least one target and one application.

Example

./productMigration.sh migrateApp –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –targNames <serverName1>,<serverName2>
–appDetails appName1!appVersion1!accessGroup1!accessGroup2,appName2!appVersion2!
accessGroup1!accessGroup2

To use the properties file in addition to the mandatory parameters, specify the hosts and products like this

migrateapp.target.targname.1=serveName1
migrateapp.target.targname.2= serverName2
migrateapp.appdetails.1= testApp!01.01.01!testApp:Administrators!testApp:Managers
migrateapp.appdetails.2=SampleApp!01.01.01!SampleApp:Administrators!SampleApp:Managers

In this example: testApp!01.01.01 is migrated first followed by SampleApp!01.01.01

Optional. Download only

To download the application without importing, set the download.only parameter in the Config Parameters common for "migrate" and "migrateApp" action section.

Example

download.only=true

Get status

Use the parameters in this category to get the status of migration requests.

Parameters in the migration.properties file

  • work.cover.id: This represents the work object ID returned after initiating a migration request.

Command line arguments

-workCoverID Specify the work cover ID of the migration request to abort.

getMigrationLog action

Returns the summary log with the status of the migration at each of the targets against which migration was initiated. If a work ID is not specified, the summary log for the last migration request that was initiated is returned.

Example

./productMigration.sh getMigrationLog –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –workCoverID pxMigReq-53

Download detailed import log

Use the parameters in this category to download detailed logs for migration requests.

Parameters in the migration.properties file

  • work.object.id: This argument represents the work object ID of the migration request on the target system. This argument can be identified from the migration log.

Command line arguments

-targetWorkObjID This parameter represents the work object ID of the migration request on the target system. This parameter can be identified from the migration log.

getImportLogs action

Downloads the detailed import logs of the products that were migrated to the target system. To get the logs of a particular request, you must specify the work object ID. The same information can be obtained from the summary log by invoking the getMigrationLog action against the source. If no work object ID is specified, the action returns the log of the last migration request available on the target. Note the change in the node URL because it should now point to the target, because this is an action against the target. The user and password should also correspond to one of the users in the target instance.

Example

./productMigration.sh getImportLogs –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user tester –pwd rules –targetWorkObjID pxMigReq-53

Cancel migration

Use the parameters in this category to cancel migration requests.

Parameters in the migration.properties file

  • work.cover.id: This argument represents the work object ID that is returned after a migration request is initiated.

Command line arguments

-workCoverID Specifies the work cover ID of the migration request to end.

abort action

This argument does not stop an import that is in progress, but stops the migration request from importing any more products.

Example

./productMigration.sh abort –url http://<serverName>:<portName>/prweb/PRSOAPServlet -user [email protected] –pwd install –workCoverID pxMigReq-53

Post-import process for applications built on earlier versions of

If you imported an application that was on an earlier version of Pega Platform, edit the application definition to include the current built on version.

For more information about editing the application definition, see Changing the built-on version of an application to the current version.