Updating file and folder paths in Portfolio

Affected versions

This article applies to all versions of Portfolio 4. These steps do not apply to vault catalogs.

Solution

Portfolio comes with an update-paths script which is used in Terminal on macOS or Command Prompt on Windows to update file paths in Portfolio catalogs.

For information on using update-paths to move a watched folder, go to Changing a Portfolio watched folder to point to a new location.

Preparing to use the update-paths script

We recommend making a backup in Portfolio before updating paths; this process is not reversible, and making a mistake could lead to a loss of catalog data. For more information, go to Backups in the Portfolio Administration online help.

On Windows, open a Command Prompt window and change to Portfolio's applications subfolder. (cd C:\Program Files (x86)\Extensis\Portfolio Server\applications)

On macOS, open the Terminal window and change to Portfolio's application subfolder (cd "/Applications/Extensis/Portfolio Server/applications/").

Calling the update-paths script on Windows

update-paths.cmd -u <username> -p <password> -c "<catalogname>" -o "<oldpath>" -n "<newpath>"

Calling the update-paths script on macOS

./update-paths.sh -u <username> -p <password> -c "<catalogname>" -o "<oldpath>" -n "<newpath>"

Parameters for the update-paths script

• -c: Name of the catalog to be updated. The catalog name must be entered exactly as it appears in the Catalogs pane in Portfolio Administration. If the catalog name has spaces or apostrophes in it, the name must be surrounded by double quotes.
• -n: Text that replaces the path specified by -o. If the path snippet has spaces or apostrophes in it, it must be surrounded by double quotes. The path should end with a colon (go to "Best practices for updating paths").
• -o: Text of the file path to be updated. If the path snippet has spaces or apostrophes in it, it must be surrounded by double quotes. The path should end with a colon (go to "Best practices for updating paths").
• -p: Password for the user account specified by -u.
• -u: Portfolio user account used to connect to Portfolio; this must be the default administrator account or a user who's a Catalog Administrator on the catalog to be updated.
• -v: Verbose mode (optional): causes the script to display extra information while it runs.

Best practices for updating paths

The update-paths script searches for the string specified in -o from the start of the folder path; it can't match a string in the middle of the path. To change a folder name, you must specify the entire file path up to the folder you want to change (go to "Changing a folder name").

You should always specify the complete folder name at the end of the old and new paths. If the paths specified in -o and -n don't end with a colon, the script adds a colon; this may affect which records get updated.

For example, you want to update the names of two folders, "Faculty Meetings" and "Faculty Portraits", to "Portland Faculty Meetings" and "Portland Faculty Portraits". You might try to use -o "::assets.example.org:Digital Assets:2019:Faculty" and -n "::assets.example.org:Digital Assets:2019:Portland Faculty" to change both at once, but the paths will get passed to Portfolio as "::assets.example.org:Digital Assets:2019:Faculty:" and "::assets.example.org:Digital Assets:2019:Portland Faculty:", which will not update the records you want. Worse, if there is a "Faculty" folder alongside "Faculty Meetings" and "Faculty Portraits", the script will change those records!

Examples of updating paths

The paths in Portfolio are specified as a Windows-style UNC path using colons instead of slashes. You can see the complete path for a given record in the Path field in the Portfolio client.

The examples below are for the macOS version of the script and assume you are using the default administrator user account and password. For Windows, use update-paths.cmd instead of ./update-paths.sh.

Changing a server name and share name

To change the name of the server and network share from "images.example.org" and "Images" to "assets.example.org" and "Digital Assets" in the "2019 Assets" catalog:

./update-paths.sh -u administrator -p password -c "2019 Assets" -o "::images.example.org:Images:" -n "::assets.example.org:Digital Assets:"

Changing a server name

It's not possible to specify just the server name for -o and -n; the update-paths script requires at least a server name and share name. Go to "Known issues with the update-paths script" for details.

To change the name of the server from "images.example.org" to "assets.example.org" (with a share name of "Digital Assets") in the "2019 Assets" catalog:

./update-paths.sh -u administrator -p password -c "2019 Assets" -o "::images.example.org:Digital Assets:" -n "::assets.example.org:Digital Assets:"

Changing a folder name

It's not possible to specify just a folder name for -o and -n; the update-paths script requires a partial path from the server name to the name of the folder. Go to "Best practices for updating paths" for details.

To change the name of a folder on the Digital Assets share from "Campus Photos" to "Campus Life" in the "2019 Assets" catalog:

./update-paths.sh -u administrator -p password -c "2019 Assets" -o "::assets.example.org:Digital Assets:2019:Campus Photos:" -n "::assets.example.org:Digital Assets:2019:Campus Life:"

Results of running the update-paths script

After you press Enter, the script will scan the records in the catalog, display the number of matching records, and ask if you want to proceed:

22799 assets match the path '::images.example.org:Images:'
Do you want to update the path to '::assets.example.org:Digital Assets:'?
Press [Y/N] and Enter:

If the record count is correct, press "y" and Enter. When the script is done running, you will see:

Updating paths........
    Job completed

Known issues with the update-paths script

The update paths script must connect to the web client service on port 8090. If the web client service listens on another port, the script will fail with an authentication error. To work around this, change the port back to 8090 in order to update paths.

The update-paths script takes up a user seat until it's finished updating records. If there are no available seats, the script will fail with an authentication error. Using the script in multiple Command Prompt or Terminal windows will take up a seat for each process; this may prevent users from logging in if the script takes up all of their available seats.

Portfolio tries to resolve the source and destination paths before updating records. A server name ("::assets.example.org") or IP address ("::198.51.100.3") by itself doesn't constitute a valid path, so trying to change the server name only will fail; to work around this, specify a share name in both the old and new paths (go to "Changing a server name").

If the new path isn't properly formatted, you will get an error: "The new path must point to a location accessible to the Portfolio Server". Common examples of incorrect formatting include:

• Using macOS- or Windows-specific paths ("D:\Digital Assets", "\\assets.example.org\Digital Assets", "smb://assets.example.org/Digital Assets")
• Escaping spaces on macOS instead of enclosing the path in double quotes (::assets.example.org:Digital\ Assets instead of "::assets.example.org:Digital Assets")