@enfocussw/switch-scripting-context 25.11.0-beta.10

package/docs/switch-api/api-http.md

@@ -0,0 +1,87 @@
+# HttpRequest & HttpResponse Classes
+
+Used in the `httpRequestTriggeredSync` and `httpRequestTriggeredAsync` entry points. Webhook subscriptions are registered via `s.httpRequestSubscribe()` in `flowStartTriggered`.
+
+## HttpRequest
+
+Represents an incoming webhook HTTP request.
+
+```ts
+request.method: HttpRequest.Method    // "POST" | "PUT" | "DELETE"
+request.path: string                  // relative URL path
+request.query: { [key: string]: string | string[] }   // query string parameters
+request.headers: { [header: string]: string }         // request headers
+request.remoteAddress: string         // client IP address
+request.body: ArrayBuffer | undefined // raw request body
+```
+
+```ts
+request.getBodyAsString(): string
+```
+Returns the raw request body decoded as a UTF-8 string.
+
+## HttpResponse
+
+Used only in `httpRequestTriggeredSync` to send a response before the function returns.
+
+```ts
+response.setStatusCode(statusCode: number): void
+```
+Set the HTTP status code (e.g. `200`, `400`, `500`).
+
+```ts
+response.setHeader(name: string, value: string): void
+```
+Set a response header.
+
+```ts
+response.setBody(data: ArrayBuffer | string): void
+```
+Set the response body.
+
+## HttpRequest.Method enum
+
+| Value | String |
+|---|---|
+| `HttpRequest.Method.POST` | `"POST"` |
+| `HttpRequest.Method.PUT` | `"PUT"` |
+| `HttpRequest.Method.DELETE` | `"DELETE"` |
+
+Available as `EnfocusSwitch.HttpRequest.Method.*` outside `main.ts`.
+
+## Webhook pattern
+
+```ts
+// flowStartTriggered — subscribe once when the flow starts
+async function flowStartTriggered(s: Switch, flowElement: FlowElement): Promise<void> {
+    await s.httpRequestSubscribe(HttpRequest.Method.POST, '/my-path', []);
+}
+
+// flowStopTriggered — unsubscribe when the flow stops
+async function flowStopTriggered(s: Switch, flowElement: FlowElement): Promise<void> {
+    await s.httpRequestUnsubscribe(HttpRequest.Method.POST, '/my-path');
+}
+
+// httpRequestTriggeredSync — handle synchronously, must set response before returning
+async function httpRequestTriggeredSync(request: HttpRequest, args: any[], response: HttpResponse, s: Switch): Promise<void> {
+    const body = request.getBodyAsString();
+    response.setStatusCode(200);
+    response.setHeader('Content-Type', 'application/json');
+    response.setBody(JSON.stringify({ received: true }));
+}
+
+// httpRequestTriggeredAsync — handle asynchronously, no response required
+async function httpRequestTriggeredAsync(request: HttpRequest, args: any[], s: Switch, flowElement: FlowElement): Promise<void> {
+    const body = request.getBodyAsString();
+    // process asynchronously...
+}
+```
+
+## Constraints
+
+- Request body limit: 1 MB (server returns HTTP 413 if exceeded)
+- Queue limit: 10,000 pending requests per element (HTTP 429)
+- Sync handler execution timeout: 1 minute (HTTP 524)
+- Default sync response if none set explicitly: HTTP 200 with body `{"status": true}`
+- Async handler only invoked if sync handler is absent or returned a 2xx status
+- Use unpredictable URL paths for security

package/docs/switch-api/api-job-patterns.md

@@ -0,0 +1,96 @@
+# Job Patterns and Behavioral Rules
+
+Common behavioral rules for file access, routing, temp file cleanup, and child jobs. These are the most frequent sources of bugs.
+
+---
+
+## File access semantics
+
+`job.get(accessLevel)` and `job.getDataset(name, accessLevel)` behave differently depending on the access level:
+
+| Access level | What it returns | Modification |
+|---|---|---|
+| `AccessLevel.ReadOnly` | Path in the element's **input folder** | Throws if the file is modified |
+| `AccessLevel.ReadWrite` | Path in a **temp location** (copy) | Auto-uploaded to the output folder when `sendTo*()` is called |
+
+Always use `AccessLevel.ReadOnly` unless you need to modify the file content.
+
+---
+
+## Temp file cleanup
+
+Switch does **not** automatically clean up files you create or pass to job-creation methods. The script is responsible:
+
+- Files/folders passed to `flowElement.createJob(path)` — delete after routing.
+- Files/folders passed to `job.createChild(path)` — delete after routing.
+- Files/folders passed to `job.createDataset(name, filePath, model)` — delete after routing.
+
+> Files accumulate between executor refreshes if not cleaned up. The executor is refreshed after 5 min idle, 5,000 tasks, 150 MB memory, or 1,024 open file handles — at which point accumulated files are removed automatically, but do not rely on this.
+
+---
+
+## Sending jobs
+
+After calling any `job.sendTo*()`:
+- Only further `sendTo*()` calls and `job.fail()` are allowed on that job object.
+- An **unmodified** incoming job can be sent to multiple connections (call `sendTo*()` multiple times).
+- A **modified** job (ReadWrite access used) must use `job.createChild()` to produce additional copies for routing to other connections.
+
+```ts
+// Route unmodified job to two connections — OK
+await job.sendToData(Connection.Level.Success);
+await job.sendToData(Connection.Level.Warning); // only if job was not modified
+
+// Route modified content to multiple connections — use createChild
+const child = await job.createChild(tempPath);
+await job.sendTo(conn1);
+await child.sendTo(conn2);
+// Clean up tempPath after routing
+await fs.promises.rm(tempPath);
+```
+
+---
+
+## Dataset writes must precede child job creation
+
+**Known issue — pending a server-side fix; remove this section once fixed.** Applies to all current versions.
+
+`job.createChild()` copies the parent's *current* datasets immediately (see [api-job.md](api-job.md#child-jobs)); `job.createDataset()` only registers a pending write, flushed to disk at the next `sendTo*()` call (see [api-job.md](api-job.md#datasets-metadata)). If a child is created *before* a dataset is written, the child inherits the job's existing dataset under that name instead. At flush time, the pending write fans out concurrently to the parent and to every child created so far, all reading from the same source file on disk — targets that already have a dataset by that name get the file **moved** into place, while targets that don't get it **copied**. When a mix of both happens against a single source file, the move wins the race and the copies fail with errors like `Could not place the file with the decoded data '...' into the datasets folder`, deterministically and on every retry (the source file is gone after the first attempt).
+
+**Rule:** perform every dataset write on a job before creating any child of it. Where a script's structure naturally interleaves the two, iterate the dataset outputs first, then the child-job outputs, rather than handling each output in one pass.
+
+Approaches that do not work:
+- Deferring `createChild()` until after routing — the SDK rejects any of `createChild`, `setPriority`, `log`, `setPrivateData`, `listDatasets`, `removeDataset`, and others once a `sendTo*()` call has been made on the job, throwing `Method is not allowed at this time. Have you called any sendTo method already?`.
+- Creating children first and only deferring *their* routing — a child is enlisted in the dataset flush at `createChild()` time, not when it's routed.
+- Calling `removeDataset()` before `createDataset()` — this only clears the parent's record and cannot reach copies a child already inherited.
+
+A dataset name that's genuinely new to the job never triggers this, since every target takes the copy path — the bug requires a pre-existing dataset of that name.
+
+---
+
+## processLater
+
+`job.processLater()` defers the job for the next `timerFired` invocation.
+
+Constraints:
+- Minimum deferral: **10 seconds** from the time `jobArrived` was called.
+- Cannot be called on jobs created with `createJob()` or `createChild()`.
+- Private data changes made before `processLater()` are preserved.
+- New datasets created before `processLater()` are **discarded**.
+
+---
+
+## Executor cleanup thresholds
+
+The Node.js executor process is recycled when any of the following thresholds is reached:
+
+| Threshold | Value |
+|---|---|
+| Idle time | 5 minutes |
+| Tasks processed | 5,000 |
+| Memory consumption | 150 MB |
+| Open file handles | 1,024 |
+
+On cleanup, any files/folders created in the temp area are removed. Always close file handles and database connections before the entry point returns.
+
+See [api-execution-environment.md](api-execution-environment.md) for how this process model affects state persistence and error handling across job invocations.

package/docs/switch-api/api-job.md

@@ -0,0 +1,156 @@
+# Job Class
+
+A `Job` represents a file or folder moving through the flow. It is passed to `jobArrived` and can be created via `flowElement.createJob()` or `job.createChild()`. Every job must be routed with a `sendTo*()` call or `fail()` before the entry point ends (or at a later time via `timerFired`).
+> Jobs obtained via `flowElement.getJobs()` throw on `getPrivateData()`, `listDatasets()`, and `getDataset()` in the same entry point invocation — private data/metadata cannot be *read* back. `setPrivateData()`/`removePrivateData()` are not restricted this way.
+## Identity
+
+```ts
+job.getName(includeExtension?: boolean): string   // default: true
+```
+Returns the filename without the internal ID prefix. Optionally strips the extension.
+
+```ts
+job.getId(): string
+```
+Returns the unique job ID (the prefix portion of the filename, without underscores).
+
+```ts
+job.isFile(): boolean
+job.isFolder(): boolean
+```
+
+## Priority
+
+```ts
+job.getPriority(): number
+job.setPriority(priority: number): void
+```
+Use `Priority.*` enum values for standard levels.
+
+## File access
+
+```ts
+job.get(accessLevel: AccessLevel): Promise<string>
+```
+Returns the local filesystem path to the job. Use `AccessLevel.ReadOnly` to read, `AccessLevel.ReadWrite` if you will modify the file/folder. Modified content is automatically uploaded on the next `sendTo*()` call. Throws if `ReadOnly` is used but the file was modified.
+
+## Routing
+
+Every job must be routed exactly once.
+
+```ts
+job.sendToNull(): Promise<void>
+```
+Discard the job (mark as completed with no output).
+
+```ts
+job.sendToSingle(newName?: string): Promise<void>
+```
+Send to the single outgoing move connection. Optionally rename.
+
+```ts
+job.sendTo(connection: Connection, newName?: string): Promise<void>
+```
+Send to a specific connection (any type). Get connections via `flowElement.getOutConnections()`.
+
+```ts
+job.sendToData(level: Connection.Level, newName?: string): Promise<void>
+```
+Send via a traffic light "data" connection at the specified level. Fails the job if no matching connection exists.
+
+```ts
+job.sendToLog(level: Connection.Level, model: DatasetModel, newName?: string): Promise<void>
+```
+Send via a traffic light "log" connection. For "data with log" connections, attaches the job as a metadata dataset to data jobs routed via `sendToData`. Discards the job if no matching connection exists.
+
+```ts
+job.sendToChannel(channelId: string, newName?: string): Promise<void>
+```
+Send to a named channel. Unlike `sendToData`/`sendToLog`, this **throws** synchronously (it does not fail-and-route the job) if the channel has no active subscriber, or if `channelId`/`newName` is empty — catch it explicitly.
+
+```ts
+job.processLater(seconds?: number): Promise<void>   // default: 300
+```
+Re-queue the job for `jobArrived` after a minimum delay (re-evaluates dynamic properties). Minimum delay: 10 seconds from `jobArrived` (a warning is logged if less). Cannot be called on newly created or child jobs. Content is not modified; newly created datasets are discarded. Private data changes are preserved.
+
+## Failure & logging
+
+See [api-logging.md](api-logging.md) for log level semantics and logging practice.
+
+```ts
+job.fail(message: string, messageParams?: (string | number | boolean)[]): void
+```
+Log a fatal error and move the job to Problem Jobs. Newly created jobs are not moved. Use `%1`, `%2`, etc. for substitution.
+
+```ts
+job.log(level: LogLevel, message: string, messageParams?: (string | number | boolean)[]): Promise<void>
+```
+Log a message including job context. To log a literal `%`, pass it as a param: `job.log(LogLevel.Info, '%1', [message])`.
+
+## Child jobs
+
+```ts
+job.createChild(path: string): Promise<Job>
+```
+Creates a new job inheriting the processing history, metadata, and private data of the parent. Takes effect immediately: the child's datasets are copied from the parent's *current* server-side state, so any pending `createDataset()` write not yet flushed by a `sendTo*()` call is not reflected in it. See [api-job-patterns.md](api-job-patterns.md#dataset-writes-must-precede-child-job-creation) — creating a child before writing a dataset is a common source of bugs. The caller is responsible for cleaning up the source file after routing.
+
+## Private data
+
+Private data is arbitrary key/value storage attached to a job and passed along with it.
+
+```ts
+job.getPrivateData(tag: string | EnfocusSwitchPrivateDataTag): Promise<any>
+job.getPrivateData(tags?: (string | EnfocusSwitchPrivateDataTag)[]): Promise<{ tag: string, value: any }[]>
+```
+Read one tag (returns the value) or multiple tags / all tags (returns an array). Returns an empty string for missing tags.
+
+```ts
+job.setPrivateData(tag: string | EnfocusSwitchPrivateDataTag, value: any): Promise<void>
+job.setPrivateData(privateData: { tag: string | EnfocusSwitchPrivateDataTag, value: any }[]): Promise<void>
+```
+Write one or multiple private data entries. Replaces existing values.
+
+```ts
+job.removePrivateData(tag: string | EnfocusSwitchPrivateDataTag): Promise<void>
+job.removePrivateData(tags: (string | EnfocusSwitchPrivateDataTag)[]): Promise<void>
+```
+Delete one or multiple private data entries.
+
+## Datasets (metadata)
+
+Datasets are named files (XML, XMP, JDF, or Opaque) attached to a job.
+
+```ts
+job.listDatasets(): Promise<{ name: string, model: DatasetModel, extension: string }[]>
+```
+List all datasets attached to the job. **Immediate**: reads server state at once, so a pending `createDataset()` write not yet flushed by `sendTo*()` will not appear.
+
+```ts
+job.createDataset(name: string, filePath: string, model: DatasetModel): Promise<void>
+```
+Attach a new dataset. **Deferred**: registers in-memory only; the file is not uploaded until the next `sendTo*()` call. Caller must clean up the source file.
+
+```ts
+job.getDataset(name: string, accessLevel: AccessLevel): Promise<string>
+```
+Returns the local path to the dataset file. Prefer `AccessLevel.ReadOnly`.
+
+```ts
+job.removeDataset(name: string): Promise<void>
+```
+Remove a dataset by name. **Immediate**: updates server state at once. Throws if it does not exist.
+
+## Variables & structured data
+
+```ts
+job.getVariableAsString(variable: string): Promise<string>
+```
+Returns the value of a Switch variable as a string.
+
+```ts
+job.getxmlData(path: any, xpathQuery: any): Promise<any>
+job.getxmpData(path: any, xpath: any): Promise<any>
+job.getJdfData(path: any, xpath: any): Promise<any>
+job.getJSONData(metadata: any): Promise<any>
+```
+Convenience helpers to read XML/XMP/JDF/JSON data from a dataset path and return it as a parsed object. On error, these log the failure and resolve to `undefined` rather than throwing or rejecting — check the result rather than wrapping the call in `try`/`catch`.

package/docs/switch-api/api-logging.md

@@ -0,0 +1,53 @@
+# Logging Practices
+
+Guidance for using `job.log()`, `flowElement.log()`, `job.fail()`, and `flowElement.failProcess()`
+— see [api-job.md](api-job.md#failure--logging) and
+[api-flow-element.md](api-flow-element.md#logging) for their signatures. `LogLevel` values are
+listed in [api-enums.md](api-enums.md). Each log call has a small performance overhead, so where
+and how often to log is a deliberate choice, not a default.
+
+## Log levels
+
+| Level | Use for |
+|---|---|
+| `Error` | The job/step failed or produced a wrong/unusable result. Often accompanies or precedes a hard stop, but can stand alone if the job continues in a degraded way. |
+| `Warning` | Something unexpected happened but processing continued successfully (a fallback was used, an optional resource was missing). |
+| `Info` | Normal, expected checkpoints worth surfacing to a flow operator without them needing debug mode (e.g. "processed 40 records", "output written to X"). |
+| `Debug` | Verbose detail for diagnosing execution. Many users leave debug logging enabled in production to self-diagnose issues and to help app developers and Enfocus Support — leave meaningful checkpoints in, but trim noisy or no-longer-useful debug logs before shipping. **`Debug` messages only reach the log database if the Switch preference "Log debug messages" is turned on** (off by default) — see [api-logs-and-dataroot.md](api-logs-and-dataroot.md#retention-and-the-debug-level-gate). |
+
+## Logging in loops
+
+Don't categorically avoid logging inside loops — per-item logs can matter (e.g. a per-job error).
+But where multiple log calls can be combined without losing clarity, prefer a single summary over
+one call per iteration, e.g. `"Found 12 matching jobs"` instead of one log line per job.
+
+## `console.log` does not work
+
+`console.log` only produces output when a debug session is attached (see
+[api-debugging.md](api-debugging.md)); in a normal run it is not visible anywhere. Never rely on it
+in production scripts — use `job.log()`/`flowElement.log()` for anything that should be visible in
+the log/message pane.
+
+## Don't double-log before a failure
+
+`job.fail()` and `flowElement.failProcess()` already log their message as a fatal error. Don't call
+`job.log(LogLevel.Error, ...)` / `flowElement.log(LogLevel.Error, ...)` with the same message
+immediately before them — it duplicates the entry in the log. Use a separate `Error` log call only
+when it conveys something distinct from the failure message.
+
+## Message formatting and the `%` gotcha
+
+Template literals are fine for ordinary log messages. But a string that may contain a literal `%`
+character — commonly external/untrusted values such as cloud storage URLs — will error if
+interpolated directly into the message, because it gets parsed as a `%1`-style substitution token.
+Workaround: pass `'%1'` as the message and the value as the parameter, e.g.:
+
+```ts
+job.log(LogLevel.Info, '%1', [urlThatMightContainPercent]);
+```
+
+## Signature gotcha: array vs. single value
+
+`job.fail(message, messageParams?: (string | number | boolean)[])` takes an **array**.
+`flowElement.failProcess(message, messageParam?: string | number | boolean)` takes a **single
+value**, not an array. Passing an array to `failProcess` is a common mistake.

package/docs/switch-api/api-logs-and-dataroot.md

@@ -0,0 +1,71 @@
+# Locating and Querying Switch's Log Database
+
+For diagnosing or validating a script from the outside — reading what the user themselves would see
+in Switch's Message pane — rather than instrumenting the script itself. See
+[api-logging.md](api-logging.md) for how a script produces these messages in the first place.
+
+## Finding the Application Data Root
+
+Switch's application data (including logs) lives under a per-installation "Application Data Root"
+folder, which is configurable and does not always sit at its default location. Resolve it in order:
+
+1. Read the `SettingsFolder` value for this Switch Server installation:
+   - **macOS:** `defaults read "com.enfocus.Switch Server" SettingsFolder`, or read the plist directly
+     at `~/Library/Preferences/com.enfocus.Switch Server.plist`.
+   - **Windows:** registry key `HKEY_CURRENT_USER\Software\Enfocus\Switch Server`, value
+     `SettingsFolder`.
+2. That value is a folder path. Inside it, open `settingsNew.xml`.
+3. In `settingsNew.xml`, find the `<UserPreference QSettingsKey="ApplicationData/ApplicationDataRoot">`
+   element — its text content is the actual configured data root path.
+
+Default data root if never changed:
+- **macOS:** `~/Library/Application Support/Enfocus/Switch Server`
+- **Windows:** `%APPDATA%\Enfocus\Switch Server`
+
+Don't assume the default — always resolve it via `SettingsFolder` → `settingsNew.xml`, since it can
+be moved to an arbitrary location (via the Application Data Root Tool).
+
+## The log database
+
+`<data root>/logs/ServerLogs.db3` is a SQLite database and is not itself independently configurable
+— it's always at this fixed path under the data root. It can be queried directly and read-only with
+any SQLite client (e.g. `sqlite3 ServerLogs.db3 "SELECT ..."`) while Switch is running.
+
+Relevant columns on the `logmessages` table:
+
+| Column | Meaning |
+|---|---|
+| `itemtime` | ISO-8601 timestamp of the log entry |
+| `type` | Log level: `debug`, `info`, `warning`, `error`, `assert` |
+| `module` | The flow element's type/display name |
+| `flow` | The flow name |
+| `element` | The flow element instance's name in that flow |
+| `operation` | The message template, with unresolved `%1`–`%9` placeholders |
+| `arg1`–`arg9` | Substitution values for the placeholders in `operation` |
+| `ticket`, `file` | Job identifier / filename, when the message relates to a specific job |
+
+The message text is stored **unresolved** — reconstruct the human-readable message yourself by
+replacing each `%N` in `operation` with the corresponding `argN`. To find a specific script's log
+output, filter on `flow` and `element` (matching the script's flow element name in the canvas) and
+order by `itemtime`.
+
+Example: find recent messages for a specific flow element, most recent first —
+
+```sql
+SELECT itemtime, type, operation, arg1, arg2, arg3
+FROM logmessages
+WHERE flow = 'MyFlow' AND element = 'MyScriptElement'
+ORDER BY itemtime DESC
+LIMIT 50;
+```
+
+## Retention and the debug-level gate
+
+- Log messages are pruned after `Logging/KeepLogMessagesForHours` (12 hours by default,
+  `settingsNew.xml`) — don't expect old entries to still be present.
+- `LogLevel.Debug` messages from `job.log()`/`flowElement.log()` only reach `ServerLogs.db3` at all
+  if the Switch preference `Logging/LogDebugMessages` ("Log debug messages") is enabled — it is
+  **off by default** in a typical install and is meant to be turned on when actively debugging. A
+  script's `Debug`-level output can be completely absent from the log database even though the
+  script correctly calls `job.log(LogLevel.Debug, ...)`; check this preference before concluding a
+  script isn't logging.

package/docs/switch-api/api-property-editors.md

@@ -0,0 +1,144 @@
+# Property Editors
+
+Property editors determine how a user enters a value in Switch Designer, and what string is
+returned by `getPropertyStringValue()` at runtime. They're set in the XML declaration via the
+`Editor` and `Type` attributes on a custom property — see
+[api-script-declaration.md](api-script-declaration.md) for the surrounding attribute grammar.
+
+All property values are returned as `string` or `string[]`. `getPropertyType()` returns one of a
+fixed set of `PropertyType` values (`literal`, `string`, `number`, `date`, `boolean`, `filepath`,
+`folderpath`, `regex`, `oauthtoken`, etc. — see [api-enums.md](api-enums.md)) describing what kind of
+value is actually present; `literal` is only one of these, not a binary "literal vs. user-entered"
+flag. Use it before interpreting the returned string, e.g. to check for a literal editor's constant
+before comparing it.
+
+`Editor` is a `;`-joined list: the inline editor's token (if any) first, then modal editor tokens in
+the order they're offered. `Type` follows from which editor(s) are chosen — see the tables below and
+[the Type reference](api-script-declaration.md#type-reference).
+
+---
+
+## Inline editors
+
+The inline editor slot is always the single token `inline` in `Editor` — what differs is `Type`.
+
+| Editor / Type | Resulting `getPropertyStringValue()` value |
+|---|---|
+| `Editor="inline" Type="string"` | Single-line text as entered |
+| `Editor="inline" Type="password"` | Text as entered (displayed masked) |
+| `Editor="inline" Type="number"` | Integer as a string |
+| `Editor="inline" Type="rational"` | Decimal as a string |
+| `Editor="inline" Type="time"` | `"hh:mm"` (zero-padded, e.g. `"09:05"`) |
+| `Editor="inline" Type="date"` | Date as entered |
+| `Editor="inline" Type="datetime"` | Date and time as entered |
+| `Editor="inline" Type="bool"` | `"No"` or `"Yes"` |
+| `Editor="inline" Type="enum:Item1;Item2;..."` | The selected item string (one of the declared values) |
+
+---
+
+## Modal editors
+
+Additional editor tokens appended after `inline` (or used alone, with no inline component). These
+open a dialog when the user clicks the editor button. All have `Type="string"` unless noted.
+
+| `Editor` token | Resulting `getPropertyStringValue()` value |
+|---|---|
+| `choosefile` | Absolute file path as a string |
+| `choosefolder` | Absolute folder path as a string |
+| `regexp` | Regular expression string as entered |
+| `filetype` | Filename pattern(s) for the selected file type |
+| `types` (`Type="filefilter"`) | `string[]` — one pattern string per selected file type |
+| `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) |
+| `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) |
+| `description` | Multi-line text as a single string (may include newlines) |
+| `scriptexp` | Result of script expression evaluated in job context, as a string |
+| `sltextwithvar` | Single-line text with variables substituted, as a string |
+| `mltextwithvar` | Multi-line text with variables substituted, as a string |
+| `conditionwithvar` | `"true"` or `"false"` after evaluating condition with variables |
+| `filepatterns` | `string[]` — one pattern string per entry |
+| `folderpatterns` | `string[]` — one pattern string per entry |
+| `stringlist` (`Type="stringlist"`) | `string[]` — one string per line |
+| `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](api-script-declaration.md#extraproperties) |
+| `external`, `external2`, … | File path to a property set edited by an external companion app |
+
+> Duplicate tokens in `Editor` are meaningless — each modal editor can only be offered once, except
+> `external` which can appear multiple times with numeric suffixes (`external`, `external2`, `external3`, …).
+
+---
+
+## Literal editors
+
+A literal editor makes a property return a **fixed string** regardless of user input. Combine it
+with another editor in the `Editor` chain (e.g. `Editor="default;choosefolder"`) to offer the
+constant as one of the choices; all literal tokens have `Type="string"`.
+
+Always call `getPropertyType()` first to check whether the value is a literal before comparing the
+string.
+
+| `Editor` token | `getPropertyStringValue()` returns |
+|---|---|
+| `default` | `"Default"` |
+| `none` | `""` (empty string) |
+| `automatic` | `"Automatic"` |
+| `nofiles` | `"No Files"` |
+| `allfiles` | `"All Files"` |
+| `allotherfiles` | `"All Other Files"` |
+| `nofolders` | `"No Folders"` |
+| `allfolders` | `"All Folders"` |
+| `allotherfolders` | `"All Other Folders"` |
+| `next` | `"Next"` |
+| `current` | `"Current"` |
+
+---
+
+## Extra XML attributes for certain editors
+
+**Dropdown (`Type="enum:..."`)** — items are embedded in the `Type` value itself:
+`Type="enum:Option A;Option B;Option C"`.
+
+**`askplugin` / `askplugin2`** — add a `SelectFromLibMes` (single) or `SelectManyFromLibMes` (multi)
+attribute to the property element to set a custom dialog message.
+
+**`stringlist`** — add a `StringListMes` attribute to show a custom message in the editor dialog.
+
+**`choosefile`** — add `Opaque="true"` to include the referenced file as an opaque payload when a
+flow is exported.
+
+**`external`** (and `external2`, …) — add matching-suffixed `ExternalEditorName`,
+`ExternalValueOverlay`, `ExternalApplication`, `ExternalArgForNew`, `ExternalArgForEdit`, and
+`ExternalFileFormat` (`Custom` or `Switch`) attributes.
+
+---
+
+## Common practices
+
+The following are recommended conventions for pairing property kinds with editor chains, not
+restrictions enforced by Switch — a script writer can combine editors differently if asked to.
+
+| Property kind | Recommended `Editor` chain | Why |
+|---|---|---|
+| Secret (password, token, API key) | `password` only | Masks the value and avoids leaking it via logs or variable inspection if a var/expression editor were combined. |
+| Scalar job-specific value (job ID, copy count, company name, date, etc.) | `inline` (`Type` matching the value) + `sltextwithvar` + `scriptexp` | Hard-coded default, plus dynamic substitution and full expression evaluation. |
+| Array/list job-specific value | `stringlist` + `mltextwithvar` + `scriptexp` | One item per line; keeps both the hard-coded and dynamic paths returning a `string[]`. |
+| Structured blob text (XML/JSON/HTML, email body) | `description` + `mltextwithvar` + `scriptexp` | Free multi-line text suits a single blob of content better than a line-per-item list. |
+| Boolean used as a `Dependency` master | `inline` only | Other properties' visibility depends on a value known at design time. |
+| Boolean consumed directly by script logic (not a `Dependency` master) | `inline` + `conditionwithvar` + `scriptexp` | Safe to toggle dynamically since nothing else depends on it for visibility. Also covers booleans that are themselves a `Dependency` *dependent* (not a master). |
+| Enum (`Type="enum:..."`) | `inline` only, always | No editor guarantees a var/expression result matches one of the declared items. |
+| File/folder path that must exist for the app to work | `choosefile`/`choosefolder` only | Switch validates the picked path exists at flow start. |
+| File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [api-flow-element.md](api-flow-element.md#properties) if the path is needed later in the flow. |
+
+`regexp`, `filetype`/`types`, `askplugin`/`askplugin2`, `oauth`, and `external` can technically be
+combined with `sltextwithvar`/`scriptexp` too, but this is uncommon in practice and not covered by a
+dedicated row above.
+
+---
+
+## Notes
+
+- **OAuth 2.0**: endpoint, client ID/secret, scope, and redirect ports are configured per-property
+  in a matching `<ExtraProperties>` child element (see
+  [api-script-declaration.md § ExtraProperties](api-script-declaration.md#extraproperties)), not in
+  `Editor`/`Type`. The script receives a ready-to-use access token string via
+  `getPropertyStringValue()`.
+- **External editor**: requires a separate companion application. The script receives a file path to
+  the property set file. Entry point `findExternalEditorPath` resolves the editor executable path.