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
.
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"
)