How to Update SOLIDWORKS PDM References in Bulk with PDMShell

To update references in bulk in SOLIDWORKS PDM, select a vault folder and run the PDMShell Update References and Check In script. It checks out every file in that folder tree, repairs their references against files in the same tree, writes a CSV report of every change, and checks the files back in with one comment. No per-file clicking and no SOLIDWORKS session needed.

Broken references are one of those problems that never arrive one at a time. Somebody copies a project, imports a customer package, or moves a set of files outside PDM, and suddenly two hundred assemblies point at paths that no longer exist. Fixing them one by one in File Explorer is slow, and opening each one in SOLIDWORKS is slower. This script is the bulk version, and it is short enough to read in a minute.

When references go wrong in a vault

File references in SOLIDWORKS PDM record which files an assembly or drawing uses and where they live. They break, or point somewhere unhelpful, in a few common situations:

• Files added from outside the vault still reference the old local or network path they came from, such as a customer folder on C: or a share that no longer exists.
• A project folder copied with Windows instead of with PDM tools keeps references to the original location.
• Data imported during a migration arrives with references that were correct on the old system but not in the new folder layout.
• Files renamed or moved outside PDM leave parents pointing at names the vault cannot find.

In every case the correct files are usually already in the vault, often in the same project folder. What is missing is the link. That is the job this script does.

What the script does

You select one vault folder and the script works on that folder and everything below it. It runs three bulk operations in order:

1. Check out every checked-in file in the folder tree.
2. Update references for the files you now have checked out on this computer.
3. Check those files back in with the comment References updated by PDMShell.

It is deliberately a bulk workflow rather than a loop over files. Three searches, three commands, and PDM does the heavy lifting in batches. You can download the script from the Update References and Check In page in the PDMShell documentation, or pick it from the PDMShell Script Library inside the app.

The complete script

If folder exists "$localPath" GoTo Folder_UpdateReferencesAndCheckIn
msgbox -value "Select a vault folder, not a file, to update references recursively." -icon "Information"
GoTo End_UpdateReferencesAndCheckIn
Folder_UpdateReferencesAndCheckIn:
cd -directory "$localPath"
checkout -search "Name=%;FolderID=$folderID;FindFiles=true;FindFolders=false;Locked=false;Recursive=true"
updatereferences -search "Name=%;FolderID=$folderID;FindFiles=true;FindFolders=false;Locked=true;LockedBy=$userName;LockedOnComputer=$computerName;Recursive=true" -directory "$localPath" -scope UpdateAllReferences -csv "$tempFolder\PDMShell-reference-update-$folderID-$GUID.csv"
checkin -search "Name=%;FolderID=$folderID;FindFiles=true;FindFolders=false;Locked=true;LockedBy=$userName;LockedOnComputer=$computerName;Recursive=true" -comment "References updated by PDMShell"
End_UpdateReferencesAndCheckIn:

How it works, line by line

Lines 1 to 3: make sure a folder was selected

If folder exists "$localPath" GoTo Folder_UpdateReferencesAndCheckIn
msgbox -value "Select a vault folder, not a file, to update references recursively." -icon "Information"
GoTo End_UpdateReferencesAndCheckIn

The first line uses a real folder existence check on $localPath, the local path of whatever the user selected. If it is a folder, the script jumps to the work section. If it is a file, the message box explains that a folder is needed and the script jumps straight to the end without touching anything.

The check is on the folder itself, not on whether the name has an extension. That matters more than it sounds. A file with no extension would fool a simple extension test, and a folder called Rev.B or Customer Files would fool it the other way. Folder names with dots and spaces both work here.

Line 5: go to the selected folder

cd -directory "$localPath"

cd makes the selected folder the working folder for the commands that follow.

Line 6: check out the folder tree

checkout -search "Name=%;FolderID=$folderID;FindFiles=true;FindFolders=false;Locked=false;Recursive=true"

The search string is where the scoping happens, so it is worth reading each token:

• Name=% matches every file name.
• FolderID=$folderID limits the search to the selected folder.
• Recursive=true includes all subfolders.
• FindFiles=true and FindFolders=false return files only.
• Locked=false returns only files that are currently checked in, so the script does not try to check out anything that is already checked out.

Line 7: update the references

updatereferences -search "Name=%;FolderID=$folderID;FindFiles=true;FindFolders=false;Locked=true;LockedBy=$userName;LockedOnComputer=$computerName;Recursive=true" -directory "$localPath" -scope UpdateAllReferences -csv "$tempFolder\PDMShell-reference-update-$folderID-$GUID.csv"

The search is the same folder tree, but this time it looks for files that are checked out (Locked=true) by you ($userName) on this machine ($computerName). That is exactly the set the previous line produced, plus anything you already had checked out there.

-directory sets where PDMShell looks for the correct files when it repairs a reference. Here it is the selected folder, so replacements are only found inside that tree, never in a sibling project that happens to contain a file with the same name.

-scope UpdateAllReferences tells it to update every reference to the first matching file name it finds in that scope. Two other scopes are available if that is too broad: UpdateBrokenReferences only touches references that are currently broken, and UpdateOutsideVaultReferenceOnly only fixes references that point outside the vault. For a cautious first run on real data, UpdateBrokenReferences is a good choice.

-csv writes a report to the Windows temporary folder, named with the folder ID and a unique $GUID so every run gets its own file. The report has the columns ID, Name, Old Reference, New Reference, Status, Error and HRESULT. It covers the reference update step only, not checkout or check in.

Line 8: check the files back in

checkin -search "Name=%;FolderID=$folderID;FindFiles=true;FindFolders=false;Locked=true;LockedBy=$userName;LockedOnComputer=$computerName;Recursive=true" -comment "References updated by PDMShell"

The same search as line 7 finds every file you have checked out on this computer in the folder tree and checks it in with one comment, so the change is easy to spot in each file’s history later.

Lines 4 and 9: labels

Folder_UpdateReferencesAndCheckIn and End_UpdateReferencesAndCheckIn are jump targets for the GoTo commands. They do not run anything themselves.

How to run it safely

1. Log in to the vault you intend to change, and load the script in the standalone visual editor.
2. Choose Run, then Browse to Folder, and pick the folder to process. Do not press Run without a selection, because if a current folder is available it may be used as the target.
3. If you select several folders, turn on Do not use optimized script execution so each folder finishes all three steps before the next one starts. Do not select a parent folder and one of its children in the same run.
4. Keep stop on error. The standalone visual Run stops when a command fails. For a saved vault script, turn on Stop script after a non-ignored error on the Handling tab and leave the checkout error ignore options off.
5. Do not run this template with the console runscript command. That runner can carry on into check in after an error, which is the one thing you do not want here.

Things to know before you run it

• It checks in more than it checked out. The final search includes any files you already had checked out on this computer in that folder tree, not only the ones this run checked out. Check in or undo your own pending work in that folder first.
• Other users are safe. Files checked out by other people, or by you on another computer, are excluded from the update and the check in.
• Duplicate names matter. UpdateAllReferences takes the first match by file name inside the folder tree. If the tree contains two different files called bracket.sldprt, review them before running, or use one of the narrower scopes. Our guide to finding duplicate file names in a SOLIDWORKS PDM vault is a quick way to check.
• Not every file type has references PDM can edit. Some PDFs and Office files are recorded as Unsupported and can make the update command fail. If the folder holds a lot of unrelated documents, narrow Name=% in all three searches, for example to SOLIDWORKS file types only.
• One failed file does not stop the batch. The update command keeps going through its results when an individual reference fails, and with stop on error enabled a failed batch stops the script before check in.
• There is no automatic rollback. A failed run can leave many files checked out, including ones that updated correctly. Read the CSV report and the command log, then decide what to check in or undo.

The script also stays in its lane. Files stay in their current folders, nothing is moved between vaults, SOLIDWORKS is never launched, and PDM permissions apply exactly as they would if you did the same steps by hand.

Test it on a copy first

Pick a small project, ideally one that is backed up or that you can restore, and run the script on that folder alone. Open the CSV report and compare a few Old Reference and New Reference rows with what you expected. Then open one assembly in SOLIDWORKS and confirm it loads its components from the right place. Once a small folder behaves, larger ones will behave the same way.

Running it unattended

The script is nine lines, which is over the five line limit of the PDMShell Free edition, so you will need a PDMShell Premium license to run it. If you plan to run it on a schedule rather than by hand, remove or replace the message box on line 2, since nobody will be there to click it, and set the folder targets and stop on error handling explicitly. Our post on automating SOLIDWORKS PDM tasks with PDMShell and Windows Task Scheduler covers the scheduling side.

It also pairs well with our move to the right range folder script: move misplaced files into their correct folders first, then update references for that tree so every parent points at the new location.

Frequently asked questions

Do I need SOLIDWORKS installed to update references with this script?

No. The script uses PDM’s own reference handling and never launches SOLIDWORKS. You need SOLIDWORKS PDM Professional and PDMShell.

Where is the report saved?

In your Windows temporary folder, outside the vault, as PDMShell-reference-update followed by the folder ID and a unique ID, with a .csv extension. Each run creates a new file.

Can I fix only broken references and leave the rest alone?

Yes. Change -scope UpdateAllReferences to -scope UpdateBrokenReferences on line 7. To fix only references that point outside the vault, use UpdateOutsideVaultReferenceOnly.

What happens to files other people have checked out?

Nothing. Every search after the checkout is limited to files checked out by you on this computer, so other people’s work is never updated or checked in.

Need help cleaning up references in your vault?

If you are dealing with a migration, an imported customer package or a vault full of outside references, we have fixed this at scale many times. Contact us and we can plan the clean up and run it with you.