The OGG migration utility helps move an existing GoldenGate Classic Architecture deployment to Microservices when the source database is being migrated. One of the things it handles is migrating Purge Trail tasks (the PURGEOLDEXTRACTS rules in the Classic Manager parameter file) into Microservices purge trail tasks. An early look at this suggested something was off whenever more than one trail was involved, so I set up a proper test: two Classic trails, each with its own retention rule, migrated to a 26ai Microservices deployment, with every REST API call captured.

Test environment

  • Source: GoldenGate 19c Classic Architecture, Oracle 19c (CDB01/PDB1)
  • Target: GoldenGate 26ai Microservices Architecture (23.26.3.0.0), Oracle 19c (CDB02/PDB2)
  • Migration utility: ogg-migration-package-23.26.2.0.2.jar (current), compared against ogg-migration-package-23.26.2.0.1.jar (previous)

Two integrated extracts on the Classic side, each with its own trail:

EXTRACT EXTAA -> trail ./dirdat/aa
EXTRACT EXTBB -> trail ./dirdat/bb

And two PURGEOLDEXTRACTS rules in the Classic Manager parameter file, deliberately using different retention units so a mix-up would be obvious:

PURGEOLDEXTRACTS ./dirdat/aa*, USECHECKPOINTS, MINKEEPHOURS 4
PURGEOLDEXTRACTS ./dirdat/bb*, USECHECKPOINTS, MINKEEPDAYS 2

Both extracts (and their replicats) were started, real transactions were committed on each so both trails had a valid CSN at checkpoint, then everything was stopped cleanly and migrated with the Java migration utility against the target Service Manager.

The bug: ogg-migration-package-23.26.2.0.1.jar

Running the previous version of the utility against this exact setup, extract and replicat migration failed outright, before the tool ever reached the Manager tasks:

Issuing [/u01/app/ogg/product/19.1.0.0.4_classic//convchk EXTCC ./dirdat/cc TRAILPATH ./dirdat/dirdat/cc]
Unexpected error while updating checkpoint trail path(s) for EXTRACT EXTCC: Call to 'convchk' failed

The trail path gets dirdat appended twice (./dirdat/dirdat/cc instead of ./dirdat/cc), convchk rejects it, and the utility rolls back the entire migration, not just the failed extract. To isolate the Manager tasks specifically, I removed the extract/replicat definitions from Classic (keeping the physical trail files and the PURGEOLDEXTRACTS rules) and re-ran the migration. That reached the Manager tasks step and failed there too, for both trails:

ERROR: Exception java.lang.IllegalArgumentException occurred creating purge task, error is Trail name (cc*) must be a 2-character sequence.
ERROR: Exception java.lang.IllegalArgumentException occurred creating purge task, error is Trail name (dd*) must be a 2-character sequence.
2 Tasks were migrated,  0 successfully, 2 with errors.

Migration of Manager Tasks Completed Successfully.

Two things worth noting here:

  • The utility takes the whole PURGEOLDEXTRACTS trail token literally, including the trailing wildcard (aa*, three characters), instead of parsing out the two-character trail name. The Microservices purge task schema only accepts a name of one or two characters (or the special value */* for everything), so validation fails.
  • This happens client-side, before any REST call is made. I confirmed this against the target’s restapi.log: the request window for this run contains no POST /services/{version}/tasks/{task} call at all. The task is not created, wildcarded or otherwise. It is just silently missing, and the console still prints “Migration of Manager Tasks Completed Successfully” right after listing two errors, which makes it easy to miss unless you check the task count on the target afterwards.

The fix: ogg-migration-package-23.26.2.0.2.jar

The same Classic setup (two trails, two differently-configured PURGEOLDEXTRACTS rules, extracts and replicats included this time) migrated cleanly with the current utility:

Migrating Manager tasks to http://10.0.0.128:7810.

Creating Task for Parameter PurgeTrail-21a20471-1.
Task Created Successfully.
Creating Task for Parameter PurgeTrail-21a20471-2.
Task Created Successfully.
2 Tasks were migrated,  2 successfully, 0 with errors.

Two separate tasks, matching the two PURGEOLDEXTRACTS rules. The restapi.log capture shows exactly what each POST /services/{version}/tasks/{task} call sent:

{
  "critical": false,
  "enabled": true,
  "command": {
    "useCheckpoints": true,
    "keep": [{ "type": "min", "units": "hours", "value": 4 }],
    "name": "purge",
    "purgeType": "trails",
    "trails": [{ "name": "aa" }]
  },
  "schedule": { "every": { "units": "hours", "value": 1 } },
  "status": "running"
}
{
  "critical": false,
  "enabled": true,
  "command": {
    "useCheckpoints": true,
    "keep": [{ "type": "min", "units": "days", "value": 2 }],
    "name": "purge",
    "purgeType": "trails",
    "trails": [{ "name": "bb" }]
  },
  "schedule": { "every": { "units": "hours", "value": 1 } },
  "status": "running"
}

Each task keeps its own trail name and its own retention rule: aa at 4 hours, bb at 2 days, exactly matching the source. No collapsing into a shared wildcard, no cross-contamination between the two retention rules. This is the trail-name parsing fixed, and it matches what the migration utility’s own release notes for this build describe:

Bug 39476155: Fixed PURGEOLDEXTRACTS migration when trail name is longer than two characters.

That is precisely the case in this test: a PURGEOLDEXTRACTS rule spec ending in a wildcard (aa*) produces a three-character token, which the fixed version now parses correctly into a two-character trail name. The double-dirdat checkpoint path bug from the previous section is also listed as fixed in the same build:

Bug 39376333: Fixed unnecessary appending and stripping of ./dirdat during trail path update.

The current utility is also more resilient in a way unrelated to either bug: in an earlier dry run against this same target, the extract and replicat patches failed because the required credential aliases did not yet exist on the target (the known OGG-15409 issue), yet the Manager tasks migration still ran to completion afterwards. The previous version aborts and rolls back everything the moment any single extract fails to patch, which is a much less forgiving failure mode for a multi-object migration.

What still holds from the original observation

Two things from the initial, single-trail test are still accurate on 23.26.2.0.2:

  • Task name: still a random generated name (PurgeTrail-21a20471-1, PurgeTrail-21a20471-2), not the source parameter’s own identity. If you have scripts or monitoring that reference a purge task by name, you will need to rename it after migration, either through the REST API or the Administration Service web UI.
  • Task status: the migration utility’s own POST body requests "status": "running", but a GET on the task right after migration shows "status": "stopped". The request is not honored; every migrated purge task comes up stopped and needs an explicit start.

Takeaways

  • If you are migrating a Classic setup with more than one trail and different purge retention per trail, do not do it with ogg-migration-package-23.26.2.0.1.jar or earlier: purge tasks whose PURGEOLDEXTRACTS rule resolves to more than two characters (which includes the common trail* wildcard form) are silently dropped, not created with the wrong scope.
  • Update to 23.26.2.0.2 or later before migrating. Both the purge-task trail-name bug and the double-dirdat checkpoint path bug are fixed there.
  • Either way, budget time after migration to rename purge tasks and start them; neither the name nor the running state survives the move.