This is a step-by-step guide to moving SOLIDWORKS PDM Dispatch actions to PDMShell without disrupting production. You will map each Dispatch action to a PDMShell command, menu or trigger point, test it on a few files, then switch over one action at a time. Dispatch and PDMShell can run in the same vault, so nothing has to change on day one.
What SOLIDWORKS PDM Dispatch does
Dispatch is an add-in that ships with SOLIDWORKS PDM Professional. An administrator builds “action scripts” in the Administration tool. Each action script has two halves:
- Activation: when the script runs. Typically a right-click menu command, or a PDM event such as a state change, check-in or add.
- Actions: what it does. A list of steps such as setting a variable, showing a message, looping over the selected documents, running a shell command, or jumping to a label when a condition is met.
For simple jobs this is enough. Clearing a variable after a transition, opening a folder, or launching an external program against the selected file are all classic Dispatch use cases. If you maintain Dispatch scripts today, the SOLIDWORKS Forum has a PDM Dispatch General Resources thread.
Before you start: is PDMShell the right fit?
This guide assumes you have already decided to move some Dispatch actions. If you are still comparing the two, read PDMShell vs Dispatch: the full comparison first. It covers when to keep Dispatch, pricing and a side-by-side table.
How PDMShell covers the same ground
PDMShell is, quite literally, a PDM shell: a command line and scripting tool for SOLIDWORKS PDM Professional. Scripts are plain text .pdmshell files made of commands like checkout, setvar, rename, transition, copy, runtask and msgbox. There are three ways to run them where Dispatch used to sit.
The PDMShell add-in
The PDMShell add-in is designed for the same class of automation Dispatch handles. Administrators open the Administration tool, expand the vault’s add-ins, right-click PDMShell and select Edit Scripts… to open the Script Editor. Each script entry has:
| Section | Purpose |
|---|---|
| Overview | Script name, enabled state, progress display, optional user cancellation |
| Permissions | PDM users and groups allowed to run the script |
| Conditions | Expression that must pass before the script runs |
| Trigger Points | Command menu text and PDM event hooks |
| Code | The .pdmshell script body |
Trigger points cover before and after events for checkout, check-in, undo checkout, get, add, delete, rename, move, copy and share, plus state changes, folder events, label events, card buttons, item selection and serial numbers. Menu commands use backslashes for grouping, for example PDMShell\Engineering\Create PDF.
The add-in runs scripts through the PDMShell command runtime directly. It does not start a separate pdmcli.exe process, and it can show a progress dialog with optional cancellation. For a before-event hook, cancelling or a script failure can cancel the pending PDM operation.
PDMShell tasks
When the automation should run in the background on a task host, appear in the Task List, or process many files, the PDMShell task add-in lets you create a PDM task (similar to the built-in Convert task) whose body is a .pdmshell script.
Calling PDMShell from Dispatch or a transition
If you are not ready to remove Dispatch, you can keep Dispatch as the trigger and move the logic into PDMShell with a Shell Command action. Leave Verb empty, point Filename at pdmcli.exe (without quotes), and pass:
runscript -source "C:\Scripts\checkin-selected-file.pdmshell" -filePath "%PathToSelectedFile%"
Workflow transitions can do the same with an Execute Command action and Wait until the started program terminates enabled. In both cases, end the script with quit so the external process closes.
Mapping common Dispatch actions to PDMShell
This is the table we use when auditing an existing Dispatch configuration.
| Dispatch concept | PDMShell equivalent |
|---|---|
| Menu command activation | Add-in script with Menu enabled and command menu text |
| PDM event activation | Add-in trigger point (before or after the event) |
| Conditions and label jumps | Add-in Conditions, visual IF branches, until |
| Dispatch variables | Placeholders such as $localPath, $fileName, $state, $userName |
| Set a data card variable | setvar -filePath "$localPath" -variableName ... -value ... |
| Show a message | msgbox -value "..." -title "..." -icon Warning |
| Check out / check in | checkout and checkin -comment |
| Rename a file | rename -filePath "$localPath" -value "..." |
| Copy a file | copy -source ... -directory ... -name ... |
| Change workflow state | transition -transitionidorname ... -filePath ... |
| Run a task | runtask -taskName ... -filePath ... |
| Shell execute | start -process ..., or keep the logic in the script itself |
| Restrict to users | Add-in Permissions (users and groups) |
| Debugging | Condition test message, visual editor, standalone PDMShell testing |
The biggest shift is mental: in Dispatch you assemble actions, in PDMShell you write a short script. Most Dispatch configurations we migrate shrink to a handful of readable lines.
Example scripts
These examples use only documented PDMShell syntax.
Clear a variable after a state change
In Dispatch this is usually a post state change activation with a Set Variable action. In the PDMShell add-in, select the after state change trigger point, add a condition, and use this code:
# Condition (in the Conditions section):
# "$state" equals "Work in Progress"
checkout -filePath "$localPath"
setvar -filePath "$localPath" -variableName "Approved By" -clear
checkin -filePath "$localPath" -comment "Approval cleared by $userName on $date"
Rename from a right-click menu
Set the command menu text to PDMShell\Rename with Revision and restrict permissions to your engineering group:
rename -filePath "$localPath" -value "$fileNameWithoutExtension $(Revision.@)$extension"
msgbox -value "$fileName renamed." -title "Rename" -icon Information
Run a task and wait for the output
This is a pattern Dispatch simply cannot express cleanly: launch a task, then wait until the generated PDF exists before continuing.
runtask -filePath "$localPath" -taskName "Publish PDF & DXF"
until -conditions "$folderPath\$fileNameWithoutExtension.pdf exists" -timeout 500
checkout -filePath "$localPath"
setvar -filePath "$localPath" -variableName Description -value "$value (PDF published)"
checkin -filePath "$localPath" -comment "PDF published"
Warn before a check-in that breaks a rule
Use a before check-in trigger point with a condition such as "$(Description.@)" equals "", so the script only runs for files with an empty description:
msgbox -value "$fileName has no description. Use Cancel on the progress dialog to stop the check-in." -title "Check-in rule" -icon Warning
Enable Show progress while running and Allow user cancellation on the script. Cancelling a before-event hook also cancels the pending PDM operation, and a script failure on a pre-event hook can cancel the command too. Turn on Always show condition test message while you validate the resolved values.
A migration approach that does not break production
We migrate Dispatch in stages rather than flipping a switch.
- Inventory. List every Dispatch action script, its activation, who uses it, and what it actually does. Retire the ones nobody uses.
- Rewrite as scripts. Write each one as a
.pdmshellfile and test it in standalone PDMShell against a sandbox folder. Store the scripts in the vault or source control so they are reviewed and versioned like any other code. - Wrap where useful. For high-risk scripts, call the new PDMShell script from the existing Dispatch action first. Users see no change, and you validate the logic in production.
- Move to the add-in. Recreate the trigger as an add-in menu command or trigger point. Start with a small administrator group in Permissions.
- Validate conditions. Turn on the condition test message so you can see exactly what PDM passed into the script.
- Reload and roll out. Menu and hook changes register when the add-in loads, so users restart Windows Explorer or log out and back in to the vault. Then expand permissions.
- Disable Dispatch. Once each PDMShell script is live, disable the matching Dispatch action script so the two never fire on the same event.
Use the Script Editor’s Export button to back up the configuration and move it from a test vault to production.
If your team is weighing PDMShell against a homegrown approach, our comparison of PDMShell vs PowerShell covers the trade-offs, and for search-driven automation the PowerShell and PDMShell search command guide is a good companion. Scheduled jobs that Dispatch could never do are covered in automating weekly check-ins with PDMShell and Windows Task Scheduler.
Where PDMShell fits
PDMShell is our product, so we are biased, but we built it because we kept hitting the same Dispatch walls on customer vaults. The add-in is part of the premium version, and the full command reference lives at pdmshell.com. If you want to try your existing Dispatch logic against it, the PDMShell trial is the quickest way to start.
FAQ
Can PDMShell and Dispatch run in the same vault?
Yes. Dispatch can even launch PDMShell scripts through a Shell Command action. Just make sure a Dispatch action and a PDMShell trigger point are not both handling the same event during migration.
Do users need PDMShell installed on their machines?
Add-in scripts run inside the PDM client through the PDMShell add-in. For PDMShell tasks, every computer selected in the task’s Execution Method must have PDMShell installed. Licensing can use a vault license pool or a machine license.
Why does my new menu command not appear?
PDM registers menu commands and hooks when the add-in loads. Restart Windows Explorer or log out and back in to the vault, and confirm the script is enabled, has menu text, and the user passes Permissions.
Can a PDMShell script cancel a PDM operation?
On before-event trigger points, yes. A script failure or user cancellation can cancel the pending operation when PDM allows it. After-event hooks cannot reverse an operation that already completed.
Need help with this?
We migrate Dispatch configurations to PDMShell regularly and can audit yours, rewrite the scripts and plan the rollout. Contact us or start with PDMShell.