@enfocussw/switch-scripting-context 25.11.0-beta.8 → 25.11.1-beta.0

package/docs/switch-api/{api-flow-element.md → flow-element.md}

@@ -1,3 +1,12 @@
+---
+id: flow-element
+category: switch-api
+order: 4
+summary: "`FlowElement`: properties, connections, job creation, logging"
+triggers:
+  - "Reading properties, creating jobs, logging, connections"
+---
+
 # FlowElement Class
 
 The `FlowElement` instance `flowElement` is passed to every entry point that operates on a flow element. It provides access to properties, connections, job creation, and logging.
@@ -5,11 +14,13 @@ The `FlowElement` instance `flowElement` is passed to every entry point that ope
 ## Identity
 
 ```ts
+// Switch 21.1+
 flowElement.getName(): string
 ```
 Returns the name of this flow element.
 
 ```ts
+// Switch 22.0+
 flowElement.getFlowName(): string
 ```
 Returns the name of the flow containing this element.
@@ -21,11 +32,11 @@ Properties are configured by the user in the Switch canvas and declared in the s
 ```ts
 flowElement.getPropertyStringValue(tag: string): Promise<string | string[]>
 ```
-Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. Throws `"Invalid tag: <tag>"` if the tag is unknown or a hidden dependent property. See [api-property-editors.md](api-property-editors.md) for editor types and their return value formats.
+Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [script-declaration.md § Dependency](../switch-project/script-declaration.md#custom-property-elements-elementfields). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally. See [property-editors.md](../switch-project/property-editors.md) for editor types and their return value formats.
 
 > **Dynamic values (Switch variables and script expressions) are only resolved when `getPropertyStringValue()` is called from `jobArrived`.** In any other entry point (e.g. `timerFired`) the raw unresolved string is returned.
 >
-> **Workaround for deferred processing:** Read property values in `jobArrived` and store them with `s.setGlobalData()`. In `timerFired`, retrieve the stored values and fetch the waiting jobs with `flowElement.getJobs(ids)`.
+> **Workaround for deferred processing:** Read property values in `jobArrived` and store them with `s.setGlobalData()`. In `timerFired`, retrieve the stored values and fetch the waiting jobs with `flowElement.getJobs(ids)` (Switch 21.0+).
 
 ```ts
 flowElement.getPropertyType(tag: string): PropertyType
@@ -40,7 +51,7 @@ Returns the English display name of the property (for use in log messages).
 ```ts
 flowElement.hasProperty(tag: string): boolean
 ```
-Returns `true` if the property exists and is visible for the current configuration.
+Returns `true` if the property exists and is visible for the current configuration. Use this to guard `getPropertyStringValue(tag)` calls on `Dependency` dependents — see the note above.
 
 ## Connections
 
@@ -58,7 +69,7 @@ Sets the interval between `timerFired` invocations. Default is 300 s. The actual
 
 ## Logging
 
-See [api-logging.md](api-logging.md) for log level semantics and logging practice.
+See [logging.md](logging.md) for log level semantics and logging practice.
 
 ```ts
 flowElement.log(level: LogLevel, message: string, messageParams?: (string | number | boolean)[]): Promise<void>
@@ -68,16 +79,17 @@ Logs a message for the flow element. Use `%1`, `%2`, etc. in the message string
 ```ts
 flowElement.failProcess(message: string, messageParam?: string | number | boolean): void
 ```
-Logs a fatal error and puts the element into the "problem process" state. `messageParam` substitutes `%1`. Throws `"Job routing is not allowed in this entry point."` if called from an entry point where routing isn't permitted.
+Logs a fatal error and puts the element into the "problem process" state. `messageParam` substitutes `%1`; before Switch 22.1, always pass it, as a string (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)). Throws `"Job routing is not allowed in this entry point."` if called from an entry point where routing isn't permitted.
 
 ## Job creation (jobArrived / timerFired)
 
 ```ts
 flowElement.createJob(path: string): Promise<Job>
 ```
-Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [api-job-patterns.md](api-job-patterns.md) for temp file cleanup rules and routing constraints.
+Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [job-patterns.md](job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [job-patterns.md](job-patterns.md#sending-jobs) for routing constraints.
 
 ```ts
+// Switch 21.0+
 flowElement.getJobs(ids: string[]): Promise<Job[]>
 ```
 Returns up to 10,000 waiting jobs by ID. Throws if `ids` is not an array, is empty, or exceeds 10,000 entries. Call at most once per entry point. Not available in concurrent `jobArrived`. Private data and metadata of returned jobs cannot be read in the same invocation.
@@ -85,6 +97,7 @@ Returns up to 10,000 waiting jobs by ID. Throws if `ids` is not an array, is emp
 ## Channels
 
 ```ts
+// Switch 22.1+
 flowElement.subscribeToChannel(channelId: string, backingFolderPath: string): void
 ```
 Subscribes to a channel to receive jobs from it. Only one subscriber per channel at a time. Must be called inside `flowStartTriggered`.
@@ -92,16 +105,19 @@ Subscribes to a channel to receive jobs from it. Only one subscriber per channel
 ## Utilities
 
 ```ts
+// Switch 24.0+
 flowElement.createPathWithName(name: string, createFolder: boolean): Promise<any>
 ```
-Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first.
+Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first. This is the recommended way to create temp files — see [job-patterns.md](job-patterns.md#temp-file-cleanup) for cleanup rules, including why this method should be preferred over ad hoc temp-file approaches like the `tmp` npm package.
 
 ```ts
+// Switch 24.1+
 flowElement.getFileCount(nested?: boolean): Promise<number>
 ```
 Returns the number of files in the active flow. If `nested` is `false`, counts only direct children; if `true` (the default, so it can be omitted), counts recursively (folders themselves are not counted).
 
 ```ts
+// Switch 24.0+
 flowElement.getScriptDataPath(): string
 ```
 Returns the path to the ScriptData folder for this element.

package/docs/switch-api/{api-http.md → http.md}

@@ -1,6 +1,15 @@
+---
+id: http
+category: switch-api
+order: 7
+summary: "`HttpRequest` / `HttpResponse` + webhook pattern"
+triggers:
+  - "Handling incoming HTTP webhooks"
+---
+
 # HttpRequest & HttpResponse Classes
 
-Used in the `httpRequestTriggeredSync` and `httpRequestTriggeredAsync` entry points. Webhook subscriptions are registered via `s.httpRequestSubscribe()` in `flowStartTriggered`.
+Used in the `httpRequestTriggeredSync` and `httpRequestTriggeredAsync` entry points. Webhook subscriptions are registered via `s.httpRequestSubscribe()` in `flowStartTriggered`. Both classes, `HttpRequest.Method`, and the subscribe methods need Switch 21.1+.
 
 ## HttpRequest
 

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

@@ -0,0 +1,178 @@
+---
+id: job-patterns
+category: switch-api
+order: 16
+summary: "`Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits"
+triggers:
+  - "Writing or reviewing job-handling code. Pair with `job.md` when you also need signatures"
+---
+
+# 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.
+
+Use `flowElement.createPathWithName()` to create temp files by default — its output lives in the executor's temp area, which Switch removes automatically on executor refresh. Even so, delete explicitly after routing rather than relying on that refresh (see below). `createPathWithName()` needs Switch 24.0+; on an older Switch, build a unique path under `os.tmpdir()` and delete it explicitly after routing.
+
+If a temp file is created some other way (e.g. `fs`/`path` writing outside the temp area, or a library that writes its own scratch files), the same rule applies: the script must delete it explicitly. Don't rely on Switch's executor-refresh cleanup for files outside the temp area — it only removes what it put there, so anything else creates a permanent leak.
+
+The [`tmp`](https://www.npmjs.com/package/tmp) npm package is common in scripts written by app creators, but it is **not recommended** here — prefer `flowElement.createPathWithName()` instead. If `tmp` is used anyway: its `setGracefulCleanup()` is not always reliable in the Switch script execution environment, so don't depend on it for cleanup — delete the file explicitly after routing regardless. Also pass `discardDescriptor: true` when creating a temp path (e.g. `tmp.fileSync({ discardDescriptor: true })`), or the open file descriptor can leak.
+
+> 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 **created via `createPathWithName()`** are removed automatically, but do not rely on this.
+
+---
+
+## Platform-independent paths
+
+Switch Server runs on both Windows and macOS. **App guideline (mandatory for apps, recommended for
+scripts):** a script package should work unmodified on either — paths returned by `job.get()`,
+`flowElement.createPathWithName()`, and similar methods use the host OS's native separator, so avoid
+hardcoding `/` or `\` when building or splitting a path, and don't assume one form when comparing or
+matching paths. Use Node's `path` module (`path.join`, `path.resolve`, `path.sep`, `path.basename`,
+etc.) instead of string concatenation.
+
+---
+
+## 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);
+```
+
+**Consistency with declared connections** (applies to every script, not just apps):
+- If `OutgoingConnections` is not `No`, the script must call some `sendTo*()` method at least once
+  for any job it actually routes. A purely timer/event-driven script that never touches a job
+  (polling an API, rotating logs, etc.) is a legitimate exception.
+- If `OutgoingConnections="Unlimited"` (more than one outgoing connection allowed), never use
+  `job.sendToSingle()` — it only makes sense when exactly one outgoing connection exists.
+- If no output is produced for a job, call `job.sendToNull()` rather than leaving it unrouted.
+- `ConnectionType="Move"` (see [script-declaration.md](../switch-project/script-declaration.md#connectionfields)):
+  never use `job.sendToData()`/`job.sendToLog()` — those are for `TrafficLight` connections only. Use
+  `job.sendTo()`/`job.sendToSingle()`.
+- `ConnectionType="TrafficLight"`: use only `job.sendToData()`/`job.sendToLog()` — never
+  `job.sendTo()`/`job.sendToSingle()`. Use `sendToData` when a Data Success/Warning/Error connection
+  is enabled in the declaration, and `sendToLog` when the corresponding Log connection is enabled.
+  Conversely, don't declare a Success/Warning/Error element the script never routes to — omit it from
+  `ConnectionFields` entirely (see the TrafficLight example in
+  [script-declaration.md](../switch-project/script-declaration.md#connectionfields)).
+  `sendToData(level)` fails the job if no connected outgoing data connection accepts that level,
+  and there is no supported way to check in advance which levels are wired up (see
+  [connection.md § Connection.Level enum](connection.md#connectionlevel-enum)). If routing at a
+  given level is optional rather than guaranteed by the flow design, expose an explicit custom
+  property that lets the flow author opt in or out, and call `job.sendToNull()` when opted out
+  instead of guessing whether `sendToData()` will succeed.
+- Prefer `job.fail()`/`flowElement.failProcess()` for genuine processing errors (see
+  [logging.md](logging.md)) over silently routing a failed job to a generic error connection —
+  reserve an error `TrafficLight` connection for cases the flow author should be able to reroute
+  downstream, not as a substitute for `fail()`.
+
+---
+
+## 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 [job.md](job.md#child-jobs)); `job.createDataset()` only registers a pending write, flushed to disk at the next `sendTo*()` call (see [job.md](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()` (Switch 22.1+) 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 [execution-environment.md](execution-environment.md) for how this process model affects state persistence and error handling across job invocations.
+
+## Driving a third-party CLI application
+
+`findApplicationPath` and the `ApplicationPath` property are the legacy-scripting mechanism for
+locating a third-party application; neither is available to Node.js scripts, and `ApplicationPath`
+is a reserved name Switch silently drops from the declaration (see
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields)). A Node.js script or
+app that shells out to an external binary resolves the path itself, using the following pattern.
+
+1. Declare an ordinary custom property for the path under a name of your own — `cliPath`, not
+   `ApplicationPath`.
+2. Give it the editor chain `automatic;choosefile;sltextwithvar;scriptexp`, with
+   `Default="Automatic"` and `Subtype="automatic"`. The `automatic` literal editor is what lets the
+   user express "find it yourself" without typing a magic string, and `getPropertyStringValue()`
+   returns the literal `"Automatic"` for it — see
+   [property-editors.md § Literal editors](../switch-project/property-editors.md#literal-editors).
+3. Resolve the path once per flow start, in `flowStartTriggered`: if the property reads
+   `Automatic`, run whatever discovery the application needs; otherwise take
+   `flowElement.getPropertyStringValue('cliPath')`. Verify the resulting path actually exists, then
+   store it in global data at `Scope.FlowElement`. If it doesn't exist, store an empty string
+   rather than leaving the tag unset.
+4. In `jobArrived`/`timerFired`, read the path back from global data. An empty string means
+   discovery failed: call `flowElement.failProcess()` so the element goes into an error state,
+   instead of failing every individual job.
+5. Remove the global data entry in `flowStopTriggered` — global data is never cleaned up
+   automatically (see [switch.md § Global data](switch.md#global-data)).
+
+Doing discovery once at flow start rather than per job keeps a filesystem search off the job path,
+and gives the operator a single clear element-level error when the application is missing.

package/docs/switch-api/{api-job.md → job.md}

@@ -1,3 +1,12 @@
+---
+id: job
+category: switch-api
+order: 5
+summary: "`Job` **signatures**: routing, file access, child jobs, private data, datasets"
+triggers:
+  - "Looking up what a `job.*` method takes, returns, or throws"
+---
+
 # 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`).
@@ -22,6 +31,7 @@ job.isFolder(): boolean
 ## Priority
 
 ```ts
+// Switch 22.1+
 job.getPriority(): number
 job.setPriority(priority: number): void
 ```
@@ -36,7 +46,7 @@ Returns the local filesystem path to the job. Use `AccessLevel.ReadOnly` to read
 
 ## Routing
 
-Every job must be routed exactly once.
+Every job must be routed exactly once. See [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs) for which `sendTo*()` method is appropriate for a given `ConnectionType`/`OutgoingConnections` declaration.
 
 ```ts
 job.sendToNull(): Promise<void>
@@ -56,7 +66,7 @@ Send to a specific connection (any type). Get connections via `flowElement.getOu
 ```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.
+Send via a traffic light "data" connection at the specified level. Fails the job if no matching connection exists. **There is no supported way to check in advance whether a connection at that level exists** — don't call `connection.getPropertyStringValue("Success")`/`"Warning"`/`"Error"` expecting to detect this; that throws an invalid-tag error, since traffic light levels aren't a readable connection property. See [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs) for the pattern (an explicit custom property plus `job.sendToNull()`).
 
 ```ts
 job.sendToLog(level: Connection.Level, model: DatasetModel, newName?: string): Promise<void>
@@ -64,23 +74,25 @@ job.sendToLog(level: Connection.Level, model: DatasetModel, newName?: string): P
 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
+// Switch 22.1+
 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
+// Switch 22.1+
 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.
+See [logging.md](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.
+Log a fatal error and move the job to Problem Jobs. Newly created jobs are not moved. Use `%1`, `%2`, etc. for substitution. When targeting Switch 20.x, always pass `messageParams`, even as `[]` (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)).
 
 ```ts
 job.log(level: LogLevel, message: string, messageParams?: (string | number | boolean)[]): Promise<void>
@@ -92,11 +104,11 @@ Log a message including job context. To log a literal `%`, pass it as a param: `
 ```ts
 job.createChild(path: string): Promise<Job>
 ```
-Creates a new job inheriting the processing history, metadata, and private data of the parent. The caller is responsible for cleaning up the source file after routing.
+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 [job-patterns.md](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 (see [job-patterns.md](job-patterns.md#temp-file-cleanup)).
 
 ## Private data
 
-Private data is arbitrary key/value storage attached to a job and passed along with it.
+Private data is arbitrary key/value storage attached to a job and passed along with it. `EnfocusSwitchPrivateDataTag` needs Switch 21.0+; before 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)).
 
 ```ts
 job.getPrivateData(tag: string | EnfocusSwitchPrivateDataTag): Promise<any>
@@ -123,12 +135,12 @@ 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.
+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. The file is uploaded on the next `sendTo*()` call. Caller must clean up the source file.
+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 after routing — see [job-patterns.md](job-patterns.md#temp-file-cleanup).
 
 ```ts
 job.getDataset(name: string, accessLevel: AccessLevel): Promise<string>
@@ -138,10 +150,12 @@ Returns the local path to the dataset file. Prefer `AccessLevel.ReadOnly`.
 ```ts
 job.removeDataset(name: string): Promise<void>
 ```
-Remove a dataset by name. Throws if it does not exist.
+Remove a dataset by name. **Immediate**: updates server state at once. Throws if it does not exist.
 
 ## Variables & structured data
 
+Everything in this section needs Switch 24.0+.
+
 ```ts
 job.getVariableAsString(variable: string): Promise<string>
 ```

package/docs/switch-api/{api-logging.md → logging.md}

@@ -1,9 +1,18 @@
+---
+id: logging
+category: switch-api
+order: 18
+summary: "Log level semantics, logging practice, `console.log` limitation, common gotchas"
+triggers:
+  - "Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls"
+---
+
 # 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
+— see [job.md](job.md#failure--logging) and
+[flow-element.md](flow-element.md#logging) for their signatures. `LogLevel` values are
+listed in [enums.md](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
@@ -13,7 +22,7 @@ and how often to log is a deliberate choice, not a default.
 | `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). |
+| `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 [logs-and-dataroot.md](../switch-project/logs-and-dataroot.md#retention-and-the-debug-level-gate). |
 
 ## Logging in loops
 
@@ -24,7 +33,7 @@ one call per iteration, e.g. `"Found 12 matching jobs"` instead of one log line
 ## `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
+[debugging.md](../switch-project/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.
 
@@ -51,3 +60,36 @@ job.log(LogLevel.Info, '%1', [urlThatMightContainPercent]);
 `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.
+
+## Placeholders instead of concatenation
+
+Build log messages with `%1`, `%2`, … placeholders and pass the dynamic values as
+`messageParams`/`messageParam`, rather than concatenating or interpolating them into the message
+string (beyond the literal-`%` escaping case above). A concatenated message can't be translated
+correctly — word order and pluralization vary by language, so a translator needs the message
+template and the substituted values kept separate. This matters even for a script that only ships in
+English today if it might ever be localized later.
+
+```ts
+// Avoid — can't be translated correctly, and hits the literal-% gotcha if fileName contains one
+job.log(LogLevel.Info, `Processed file ${fileName} in ${seconds}s`);
+
+// Prefer
+job.log(LogLevel.Info, 'Processed file %1 in %2s', [fileName, seconds]);
+```
+
+## Message quality
+
+- Log messages are user-facing text — proofread them. A message with grammatical errors or typos
+  looks unfinished and undermines trust.
+- Log an `Error` when a custom `validateProperties`/`validateConnectionProperties` check returns
+  `valid: false` for a tag, and when `getLibraryForProperty`/`getLibraryForConnectionProperty` would
+  otherwise return an empty list — see [entry-points.md § Property UI callbacks](entry-points.md#property-ui-callbacks).
+  Silently returning `false`/`[]` with no log line leaves the user without any explanation.
+
+## Log volume
+
+**App guideline (mandatory for apps, recommended for scripts):** don't over-log. Beyond the
+[Logging in loops](#logging-in-loops) guidance, avoid `Info`/`Debug` calls that don't help a flow
+operator or support engineer understand what happened — every extra message adds noise (and
+translation burden, for an app) without adding signal.

package/docs/switch-api/{api-switch.md → switch.md}

@@ -1,3 +1,12 @@
+---
+id: switch
+category: switch-api
+order: 3
+summary: "`Switch` (`s`): global data, webhooks, abort, server utilities"
+triggers:
+  - "Using global data, webhooks, abort, or server settings"
+---
+
 # Switch Class
 
 The `Switch` instance `s` is passed to every entry point. It provides global data storage, webhook subscription, abort handling, and server utilities.
@@ -9,12 +18,12 @@ Global data is key/value storage shared across entry point invocations, scoped b
 | Scope | Shared across |
 |---|---|
 | `Scope.FlowElement` | This script element instance only |
-| `Scope.FlowElements` | All instances of the same script in the same flow |
+| `Scope.FlowElements` | All instances of the same script in the same flow (Switch 22.0+) |
 | `Scope.Element` | All instances of the same script across all flows |
-| `Scope.Flow` | All elements in the same flow |
+| `Scope.Flow` | All elements in the same flow (Switch 22.0+) |
 | `Scope.Global` | Any element in any flow — use sparingly; prefix tags with your company name |
 
-Dates stored via `setGlobalData` are returned as strings by `getGlobalData` — parse them in your script.
+Dates stored via `setGlobalData` are returned as strings by `getGlobalData` — parse them in your script. Before Switch 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)).
 
 ```ts
 s.getGlobalData(scope: Scope, tag: string, lock?: boolean): Promise<any>
@@ -40,6 +49,8 @@ Delete one or multiple global data entries.
 
 ## Webhooks
 
+Both methods need Switch 21.1+.
+
 ```ts
 s.httpRequestSubscribe(method: HttpRequest.Method, path: string, args: any[]): Promise<void>
 ```
@@ -53,6 +64,7 @@ Unsubscribe a previously registered webhook.
 ## Abort
 
 ```ts
+// Switch 22.1+
 s.setAbortData(abortData: any): void
 ```
 Store a value that will be passed to the `abort` entry point when the configured abort timeout expires.
@@ -60,16 +72,68 @@ Store a value that will be passed to the `abort` entry point when the configured
 ## Server utilities
 
 ```ts
+// Switch 24.0+
 s.getPreferenceSetting(settingKey: string): Promise<any>
 ```
 Retrieve a Switch preference setting. `settingKey` format: `"settingGroup"` or `"settingGroup/settingName"`. Returns `''` if the setting/group doesn't exist. Any field whose name contains `password`, `pwd`, or `secret` is redacted in the result. The returned value is JSON-stringified, not a raw object.
 
 ```ts
+// Switch 24.0+
 s.getServerVersion(): number
 ```
-Returns the Switch server version as `majorVersion + updateNumber/100` (e.g. Switch 25.11 → `25.11`), not a literal version string — don't parse it as one.
+Returns the Switch server version as `majorVersion + updateNumber/100` (e.g. Switch 25.11 → `25.11`), not a literal version string — don't parse it as one. The method doesn't exist before Switch 24.0, so it can't detect older versions; see [api-versions.md § Checking at runtime](api-versions.md#checking-at-runtime).
 
 ```ts
+// Switch 22.0+
 Switch.tr(str: string): string
 ```
 Static method. Marks a string literal for translation (used by SwitchScriptTool). Returns the string unchanged at runtime.
+
+### Translation extraction rules
+
+`SwitchScriptTool --generate-translations` extracts strings by **static analysis of the source
+text**, not by running it. It only ever sees a `Switch.tr(...)` call whose argument is a string
+literal, spelled exactly like that. Anything it can't resolve statically is silently skipped — no
+error, no warning, just a missing entry in the `.ts` file. Always check the generated `.ts` for the
+strings you expected.
+
+What extraction handles:
+
+```ts
+Switch.tr('single');            // single, double and backtick quotes all work
+Switch.tr(`multi
+line`);                         // multi-line literals work
+Switch.tr('one ' + 'two ');     // concatenation of literals works
+// The tr() call doesn't have to sit at the point of use:
+const s = Switch.tr('Predefined string');
+await job.log(LogLevel.Info, s);   // extracted, and translated at runtime
+```
+
+What it does **not** handle:
+
+```ts
+const t = Switch.tr;               // aliasing the function: never extracted
+await job.log(LogLevel.Info, t('nope'));
+
+const token = getToken();
+Switch.tr('prefix ' + token);      // concatenation with a non-literal
+Switch.tr(`prefix ${token}`);      // template interpolation
+Switch.tr('Job ID = ' + job.getId());
+```
+
+For dynamic values, mark the template and pass the values as `messageParams` — the template gets
+translated, the substituted values don't:
+
+```ts
+await job.log(LogLevel.Info, Switch.tr('Job ID = %1'), [job.getId()]);
+```
+
+Arguments can themselves be translated by wrapping them separately:
+
+```ts
+const mode = readOnly ? Switch.tr('Read-only') : Switch.tr('Regular');
+await job.log(LogLevel.Info, Switch.tr('Job ID = %1, Mode = %2'), [job.getId(), mode]);
+```
+
+See [logging.md § Placeholders instead of concatenation](logging.md#placeholders-instead-of-concatenation)
+for the same rule stated from the logging side.