Placeholders and functions
Quick start
Use placeholders to read a value and functions to work with it:
| Syntax | Meaning | Example |
|---|---|---|
$name |
A property of the current item. | $workflow reads its workflow name. |
$(Variable.Configuration) |
A PDM data-card value. | $(Description.@) reads Description from the @ tab. |
${function(...)} |
A calculation or lookup. | ${trim(" Part A ")} returns Part A. |
${global.Name} |
A value saved with setglobal. |
${global.Project} reads the saved project value. |
Use these in command parameters or script conditions. In the console, paths, search queries and CSV report filenames can use functions and saved variables. For example:
copy -source "C:\Templates\EC_Template.xml" -directory "C:\Vault\${global.Project}\EC" -name "${global.ECNumber}.xml"
setvar -filePath "${global.ECNumber}.xml" -variableName "ec_number" -value "${global.ECNumber}"
Console expressions use the current folder unless the command supplies a file. Names and values that apply to each search result, such as copy -name and setvar -value, evaluate for that item. File placeholders therefore need a file context; a saved script can receive one through runscript.
Passwords remain literal. Waiting conditions evaluate while waiting. Text stored in a global or task variable is inserted as data, so expressions inside that stored text do not run again.
msgbox -value "File: $fileName"
msgbox -value "Description: $(Description.@)"
msgbox -value "Code: ${substring($fileNameWithoutExtension, 3)}"
Common placeholders
| Value | Placeholders |
|---|---|
| File | $fileName, $fileNameWithoutExtension, $extension, $filePath, $id |
| File status | $version, $revision, $state, $stateID, $workflow, $workflowID |
| Folder | $folderPath, $folderName, $folderID |
| Vault and user | $vaultName, $vaultRootFolder, $username, $windowsUser |
| Date and time | $yyyy, $MM, $dd, $HH, $mi, $ss, $timestamp |
| Existing value | $value in commands that supply it, such as setvar |
Full placeholder reference · Event placeholders · Session variables
File/folder picker commands store results in ${local.Name} for the current script invocation, or ${global.Name} with -global. Local values work in evaluated parameters and conditions; nested scripts have independent locals and restore the caller's values afterwards. Missing or expired locals are errors. Unlike a function, a picker is a separate interactive command and cannot run in unattended tasks or MCP.
Functions
Use ${name(arguments)}. Names are case-insensitive. Brackets in a signature mean an optional argument; do not type the brackets. A complete ${...} expression can be used as a parameter value without outer quotes. In visual parameter fields, enter the expression normally; the editor handles command-level quoting. See expressions containing quotes for copyable script and raw-script examples.
Text
Text examples, regex, and edge cases.
| Function | Purpose | Example |
|---|---|---|
${upper(value)} |
Converts text to invariant uppercase. | ${upper("part")} → PART |
${lower(value)} |
Converts text to invariant lowercase. | ${lower("PART")} → part |
${trim(value)} |
Removes surrounding whitespace; keeps internal spaces. | ${trim(" A ")} → A |
${substring(value, start[, length])} |
Extracts text from a zero-based start, optionally limited by length. | ${substring("ABC123", 3)} → 123 |
${left(value, count)} |
Returns the first count characters. |
${left("ABC", 2)} → AB |
${right(value, count)} |
Returns the last count characters. |
${right("ABC", 2)} → BC |
${len(value)} |
Returns the number of characters in value. |
${len("ABC")} → 3 |
${pos(value, search)} |
Returns the zero-based position of search in value, or -1 when it is not found. |
${pos("A-B", "-")} → 1 |
${replace(value, old, new)} |
Replaces all literal occurrences of old with new; it does not interpret regex patterns. |
${replace("A B", " ", "_")} → A_B |
${before(value, search)} |
Returns the text before search. |
${before("A-B", "-")} → A |
${after(value, search)} |
Returns the text after search. |
${after("A-B", "-")} → B |
${regex(value, pattern[, group])} |
Extracts a match or an optional numbered/named capture. | ${regex("A123", "[0-9]+")} → 123 |
${regexReplace(value, pattern, replacement)} |
Replaces all regex matches, with numbered or named capture substitutions. | ${regexReplace("A123", "[0-9]+", "X")} → AX |
Numbers
Nested expressions and number formatting.
| Function | Purpose | Example |
|---|---|---|
${inc(value[, amount])} |
Adds 1, or the supplied amount. | ${inc(7)} → 8 |
${dec(value[, amount])} |
Subtracts 1, or the supplied amount. | ${dec(7)} → 6 |
${add(left, right)} |
Adds two numbers. | ${add(7, 2)} → 9 |
${sub(left, right)} |
Subtracts right from left. |
${sub(7, 2)} → 5 |
${mul(left, right)} |
Multiplies two numbers. | ${mul(7, 2)} → 14 |
${div(left, right)} |
Divides left by right. |
${div(8, 2)} → 4 |
Workflow and state functions
Use a file ID, complete path, or filename in the current PDM folder. Omit the target to use the current file. In an IF condition: ${workflow(12345)} equals "Engineering". See conditions.
| Function | Purpose | Example |
|---|---|---|
${workflow([target])} |
Reads a workflow name. | ${workflow(12345)} |
${workflowID([target])} |
Reads a workflow ID. | ${workflowID("Part.sldprt")} |
${state([target])} |
Reads a state name. | ${state()} |
${stateID([target])} |
Reads a state ID. | ${stateID(12345)} |
Sheet metal
${isSheetMetal()} checks the active part configuration or the parts shown in a drawing's views. Pass a file ID or vault path to check another file. Cache the drawing and its referenced parts before running the check.
Toolbox parts
${isToolbox()} returns true if the current part has the SOLIDWORKS Toolbox flag. To check another cached part, pass its ID or path, for example ${isToolbox(12345)}. Drawings and assemblies return false.
Checkout state functions
Uses the current file or an optional file path. Relative paths use the current PDM folder. A false result alone does not prove that a file exists.
| Function | Purpose | Example |
|---|---|---|
${isCheckedOut([filePath])} |
Returns true when the current file, or the optional file path, is checked out. |
${isCheckedOut()} |
${isCheckedByMe([filePath])} |
Returns true when the current PDM user has the current file, or the optional file path, checked out. |
${isCheckedByMe("Part.sldprt")} |
${isCheckedOutByUsername(userName[, filePath])} |
Returns true when the named PDM user has the current file, or the optional file path, checked out. |
${isCheckedOutByUsername("Admin")} |
${checkedOutOnComputer([filePath])} |
Returns the checkout computer for the current file or optional file path. | ${checkedOutOnComputer()} |
Revision functions
Uses the current file or an optional file path. These functions read or calculate values; they do not change the file. See revision schemes, counters, and examples.
| Function | Purpose | Example |
|---|---|---|
${revision([filePath])} |
Current full revision display value. | ${revision()} |
${nextRevision([filePath])} |
Calculates the next revision display value without changing the file. | ${nextRevision()} |
${revisionComponentValue(componentName[, filePath])} |
Current display value of a named revision component. | ${revisionComponentValue("ComponentName")} |
${nextRevisionComponentValue(componentName[, filePath])} |
Next display value of a named revision component. | ${nextRevisionComponentValue("ComponentName")} |
${revisionComponentCounter(componentName[, filePath])} |
Current numeric counter of a named revision component. | ${revisionComponentCounter("ComponentName")} |
${nextRevisionComponentCounter(componentName[, filePath])} |
Next numeric counter of a named revision component. | ${nextRevisionComponentCounter("ComponentName")} |
${revisionNumberName([filePath])} |
Assigned revision scheme name. | ${revisionNumberName()} |
${revisionNumberId([filePath])} |
Assigned revision scheme ID as text. | ${revisionNumberId()} |
${revisionComponents([filePath])} |
Comma-separated names of the assigned revision components. | ${revisionComponents()} |
${hasRevisionScheme([filePath])} |
Whether the file has an assigned revision scheme. | ${hasRevisionScheme()} |
${canIncrementRevision([filePath])} |
Whether PDM allows a revision increment; does not increment it. | ${canIncrementRevision()} |
${isRevisionValueValid(value[, filePath])} |
Whether a value matches the file's revision component format. | ${isRevisionValueValid("A")} |
Input and lookup
Prompt, CSV lookup, and serial-number examples. input opens a dialog; serialNumber consumes a real number each time it runs.
| Function | Purpose | Example |
|---|---|---|
${input(title, message[, defaultValue])} |
Same as $input(title, message[, defaultValue]), using the standard function expression syntax. |
${input("Title", "Enter a value")} |
${lookup(csvPathOrPdmFileId, value)} |
Reads a CSV file, finds value in the first column, and returns the matching value from the second column. |
${lookup("C:/Data/codes.csv", "A100")} |
${serialNumber(name)} |
Allocates and returns the next value from the named SOLIDWORKS PDM serial number. | ${serialNumber("PartNumber")} |
${folderVariable(path, name)} |
Reads a folder's data-card variable by complete path, without changing directories. | ${folderVariable("C:/Vault/Project", "Title")} |
${referencedDocumentRevision([drawingIdOrPath])} |
Gets the PDM revision of the drawing's first referenced part or assembly. Defaults to the current drawing. | ${referencedDocumentRevision()} |
${referencedDocumentVariable(name, [drawingIdOrPath])} |
Reads a card variable from that model using the drawing view's configuration. | ${referencedDocumentVariable(Description)} |
These drawing lookups require a locally cached drawing and Document Manager. Multiple models use the first reference; missing or inaccessible references report an error. An optional drawing ID or path selects a different drawing, for example ${referencedDocumentRevision(12345)}.
Aliases: increment, decrement, subtract, multiply, divide, serialNbr, and isCheckedOutByMe are also supported.
Try an expression
Use the Expression Evaluator to preview a value. In Conditions or Evaluate, press Ctrl+Space for suggestions. Opening suggestions does not execute a function.
Unknown functions and many invalid expressions remain unchanged. Workflow/state lookups raise errors for invalid or unavailable targets. Check the result before using it in a command.