Table of Contents

updatereferences

Free

Description

Updates file references inside the SOLIDWORKS PDM vault.

The updatereferences command modifies references stored inside files, without opening SOLIDWORKS, and allows you to:

  • Update references for a single file
  • Update references for multiple files using a search
  • Resolve references by locating matching files inside a specified directory
  • Control which references are updated using a scope parameter

This command is especially useful for fixing broken references, updating references after migrations, or correcting references that point outside the vault.

Syntax

updatereferences (-filePath <parent> | -id <parentId> | -search <query>) [-oldReferencePathOrID <pathOrId> -newReferencePathOrID <pathOrId>] [-directory <folder>] [-scope <scope>] [-recursive] [-csv <report.csv>]

Use -id as an alternative to -filePath for the same operand. A required target still needs one selector, even though each alternative is optional individually. See File IDs and paths for selection rules and command-specific exceptions.

Parameters

Parameter Alias Required Description
-filePath No Updates references for a single file. When specified, only this file is processed and the search parameter is ignored.
-search No Search query used to find files whose references should be updated. The search is scoped to the current directory. Go to Advanced Search article on PDMShell.com for more information...
-directory -dir No Limits where replacement references are searched. Only files found under this directory will be used to update references. Defautlts to current directory if not found.
-oldReferencePathOrID No Exact old reference: positive PDM file ID or complete absolute file path. Use with -newReferencePathOrID.
-newReferencePathOrID No Replacement file ID or complete absolute path to an existing file in the connected vault.
-checkout No Check out unlocked parents and check them back in after verified success. Preserve existing owned checkouts. Continue other search results after a parent fails.
-scope No Controls which references are updated. Valid values: UpdateOutsideVaultReferenceOnly, UpdateBrokenReferences, UpdateAllReferences.
-recursive No When used with search, includes subfolders of the current directory when locating files whose references will be updated.
-csv No Captures update references results when updating multiple files and saves them to a CSV file. You must include the extension. Example: -csv report.csv
-id No Positive PDM file ID instead of -filePath, identifying the same file that -filePath describes (including a macro, input CSV or existing output file). Requires a connected vault. Shared files with multiple locations require an exact -filePath. Resolving the ID itself does not download, check out or check in the file; the requested command still performs its normal operation.

More about parameters

  • filepath
    Optional. Updates references for a single file.

    • If a relative path is provided, it is resolved against the current directory.
    • When specified, the search parameter is ignored.

  • search
    Optional. Search query used to find files whose references should be updated.

    • The search is scoped to the current directory.
    • Supports % wildcards.
    • Can be combined with recursive.

  • directory
    Optional. Defines where replacement references are searched.
    Only files found under this directory will be used when resolving and updating references.

  • scope
    Optional. Controls which references are updated.
    Valid values:

    • UpdateOutsideVaultReferenceOnly – Updates references that point outside the vault
    • UpdateBrokenReferences – Updates references that are missing or broken
    • UpdateAllReferences – Updates all references found in the file

  • recursive
    Optional. When used with search, includes subfolders of the current directory when locating files whose references should be updated.

  • csv Saves the update references operations in a csv file.

Behavior

  • Operates directly on file reference data
  • Does not open SOLIDWORKS
  • Requires files to be checked out
  • Uses vault searches to locate replacement references
  • Without the explicit reference pair, updates references by matching file names inside the specified directory scope
  • Commits changes directly back into the file
  • Failures and cancellations are preserved in the final command result. A later successful file in the same run does not hide an earlier failed update.

Replace one specific reference

For a CSV containing different parent/old/new mappings, use updatereferencemap.

Use both reference parameters to replace a file even when its name changes:

updatereferences -id 500 -oldReferencePathOrID 123 -newReferencePathOrID 456

Here, 500 identifies the parent, 123 the old referenced file, and 456 the replacement. Check out the parent first. It remains checked out so you can inspect the result before checking it in.

You can also use complete paths:

updatereferences -filePath "C:\Vault\Machine.sldasm" -oldReferencePathOrID "C:\Vault\Bracket copy.sldprt" -newReferencePathOrID "C:\Vault\Bracket.sldprt"
  • Each reference accepts a positive file ID or a complete absolute path. Relative paths and filenames alone are rejected.
  • Shared file IDs with several locations require an exact path.
  • The replacement must exist in the connected vault. An old absolute path may identify a broken reference.
  • Both parameters are required together. Do not combine them with -directory or -scope.
  • Only the exact old reference is replaced, including multiple occurrences. A same-named file in another folder is left alone.
  • Without -checkout, parents must already be checked out by you in the selected folder on this computer.
  • Saved references are verified after writing. If verification fails, inspect the checked-out parent before checking it in; changes may be partial.

To apply the same replacement to several selected parents, use -search and optionally -csv for a results report. Search selects the parents to update; it does not discover their parents. A parent without the old reference reports NoChanges. Failed parents are recorded while remaining search results continue.

Add -checkout to check out unlocked parents and check them back in after the update is saved and verified:

updatereferences -id 500 -oldReferencePathOrID 123 -newReferencePathOrID 456 -checkout

Existing checkouts owned by you are preserved. A checkout, update, verification, or check-in failure leaves the affected parent for inspection and does not stop other search results. Failed acquired checkouts are not automatically undone or checked in.

Review the results before checking in any parents left checked out. Any failed update makes the overall command fail, even if other files succeed. Leave failed parents checked out for inspection instead of checking in every search result unconditionally.

Examples

Update only references that point outside the vault

updatereferences -filepath speaker.sldasm -directory Libraries -scope UpdateOutsideVaultReferenceOnly

Update broken references for all assemblies in the current folder

updatereferences -search %.sldasm -scope UpdateBrokenReferences

Remarks

  • Either filepath or search must be specified.
  • If both are provided, filepath takes precedence.
  • The search parameter only searches within the current directory unless recursive is specified.
  • Without the explicit reference pair, reference resolution is based on matching file names within the directory scope.
  • Filename-based resolution uses the first matching file found. Explicit replacement uses the exact supplied path or ID.
  • This command modifies files directly; use with care in controlled workflows.
Edit this page