updatereferencemap

Replace references in checked-out parent files using a CSV. Each row identifies the parent to update, the old referenced file, and its replacement.

updatereferencemap -csv "C:\Reports\reference-map.csv"

CSV format

Reference,Old,New
C:\Vault\Machine.sldasm,C:\Vault\Bracket copy.sldprt,C:\Vault\Bracket.sldprt
C:\Vault\Machine.sldasm,C:\Vault\Shaft copy.sldprt,C:\Vault\Shaft.sldprt
C:\Vault\Fixture.sldasm,C:\Vault\Bracket copy.sldprt,C:\Vault\Bracket.sldprt

Column	Meaning
`Reference`	Complete path to the parent file to modify.
`Old`	Complete path to the referenced file being replaced.
`New`	Complete path to the replacement file in the connected vault.

All three columns require complete absolute paths. IDs, relative paths, and filenames alone are rejected. Use quotes around CSV fields containing commas. The headers are required; their order and capitalization may vary.

Parameters

Parameter	Required	Description
`-checkout`	No	Check out unlocked parents and check them back in after verified success. Existing owned checkouts stay checked out.
`-csv`	Yes	Input CSV. Its path may be absolute or relative to the current vault folder. This is not an output report.

Before running

Without -checkout, check out the parent files on this computer using your current PDM account. Parents and replacement files must exist in the connected vault. The old path may identify a broken reference.

Add -checkout to manage checkout and check-in:

updatereferencemap -csv "C:\Reports\reference-map.csv" -checkout

An unlocked parent is checked out and checked back in only after all its replacements are saved and verified. A parent already checked out by you stays checked out. Another user's checkout, or a checkout on another computer, is reported as a failure.

Checkout, replacement, verification, or check-in failures affect only that parent. The remaining parents continue. Failed acquired checkouts stay available for inspection; the command does not undo them automatically.

The command validates the full CSV before updating files. It ignores identical duplicate mappings and rejects conflicting replacements or chains such as A → B followed by B → C for the same parent. Map each old reference directly to its final replacement.

One update per parent

Rows with the same complete Reference path are processed together, even when they appear in different parts of the CSV. Path matching ignores capitalization. All replacements for that parent are written together, then the file is reopened once to verify the saved references. Two files with the same name in different folders are separate parents.

Results

Only references matching the exact old path are replaced; other references remain unchanged.
Saved references are verified once after all mappings for that parent are written. Without -checkout, parents remain checked out for inspection and later check-in.
Progress counts parents, with results for each CSV row. A missing old reference reports NoChanges.
If a parent fails, none of its mappings are reported as verified, and other parents continue. All replacement targets for a parent are checked before writing. Inspect failed parents before retrying because a write may be partial.
Any failed mapping makes the overall command fail, even when other parents succeed. Do not follow a failed run with an unconditional check-in of every parent.
Cancellation stops between parents. Completed parents keep their checkout/check-in state. A canceled update is not automatically checked in.