Async Migration Serviceability - quality-manager/onboarding GitHub Wiki

Serviceability:

User WIKI about Async Migation

Migration Admin Panel:

  • The migration admin panel is available in the browser to admins via https://[fully qualified hostname]:9443/qm/migration. See https://jazz.net/wiki/bin/view/Main/RqmApi#contextRoot for more information about your servers configured URL and port.
  • Migrators can be started and stopped from the admin panel
  • If a critical error occurs, the migrators will auto disable. IBM Rational Support should be contacted prior to restarting migrators.

Managing migrator lifecycle through REST API:

Commands:

  • initialize:

    • description: Changes state of all existing items to not migrated and adds new items if not already in migration table. Does not migrate any items which the migrator detects as already migrated.
    • purpose: Useful in the event some items that should have been migrated were not added to the migration queue to be migrated. This could have been result of an issue with the migrator initialization query. Likely this will require a code fix to be applied prior to running this command.

  • force:

    • description: Changes the status of all migrated items to 'not migrated' and will then migrate all items even if the migrator determines it has already been migrated.
    • purpose: Useful if the migrator is not functioning properly and has created bad data on migration. This will require a code fix prior to running this command.

  • retry:

    • description: Changes the status of only the failed items and will migrate only those items again.
    • purpose: Useful when an issue can be isolated to a particular set of items. The problem could be bad data or a migrator code problem in which a code fix will be required prior to running this command.

REST API Lifecycle Command Definitions:

Migrator ID's in 605

  1. AttachmentMigrator
  2. StepCountScriptAndTestcaseMigrator
  3. StepCountTestResultMigrator
  4. StepCountTestSuiteResultMigrator

Command execution

  • Confirmation of command execution can be observed in the Asynchronous Migration Framework log.

  • Commands are only executed when the async task runs. So there can be a delay in execution equal to the time delay of the async task which is 1 minute by default.

  • Commands should only be executed one at a time. Wait until there is logging confirmation that the command is complete before issuing additional commands.

Command syntax for execution against all projects:

  • initialize: POST {{host}}{{context}}/migration/initialize/{{migratorId}}

    • parameter daysSince can be added to initialize recent items created n days previously

  • force: POST {{host}}{{context}}/migration/force/{{migratorId}}

  • retry: POST {{host}}{{context}}/migration/retry/{{migratorId}}

Command syntax for execution against a particular project by using the project stream UUID

  • initialize: POST {{host}}{{context}}/migration/initialize/{{migratorId}}/{{streamUUID}}

    • parameter daysSince can be added to initialize recent items created n days previously

  • force: POST {{host}}{{context}}/migration/force/{{migratorId}}/{{streamUUID}}

  • retry: POST {{host}}{{context}}/migration/retry/{{migratorId}}/{{streamUUID}}

REST API Status migration status per project area

This can be used to get a JSON response of the progress by project area / stream

  • {{host}}{{context}}/properties/ASYNC_MIGRATOR_PROCESS_BY_STREAM

Inspecting Migration Table

  • The migration table tracks all items that are being migrated.

  • Initially when the server is started after upgrade the migration table is populated with all items that should be migrated.

  • After initialization, then the actual migration starts during which time the migration table is updated with the status for each item being migrated.

  • The migration table is : DEPLOYMENT.MIGRATION_ITEM

Configuring migration speed:

  • Within Advanced Server Properties search for AsynchronousMigrationTask

  • The number of items per task execution and the delay can be changed in this section.

  • The migration logs can be analyzed to determine if making any changes here would be appropriate.

References:

  • What a normal migration log looks like...

Development Testing

Migration can be forced in the dev environment using the following REST API's

  • Initialize all items for a migrator
    • POST {{host}}{{context}}/migration/initialize/{{migratorId}}?daysSince=-1
  • Force Execute migration of all items
    • POST {{host}}{{context}}/migration/force/{{migratorId}}