@enfocussw/switch-scripting-context 0.1.0

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

@@ -0,0 +1,238 @@
+---
+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, locking shared global data, 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.
+
+---
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- File access semantics
+- Temp file cleanup
+- Platform-independent paths
+- Sending jobs
+- Dataset writes must precede child job creation
+- processLater
+- Shared state in global data
+- Executor cleanup thresholds
+- Driving a third-party CLI application
+<!-- docs-index:contents end -->
+
+## 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**.
+
+---
+
+## Shared state in global data
+
+The deferred-processing pattern (register each job in global data in `jobArrived`, fetch and
+process the registered jobs in `timerFired` with `flowElement.getJobs(ids)`) is a read-modify-write
+of a shared tag. In `Concurrent` mode several `jobArrived` invocations run at once, so without a lock
+two of them can read the same list and one overwrites the other's addition.
+
+Lock the tag, change it, and write it back straight away. Do the slow work (fetching, processing and
+sending jobs) after the lock is released, because every other invocation that reads the tag waits
+for as long as the lock is held. The locking rules this relies on, including the one-lock-per-
+invocation gotcha, are in [switch.md § Locking](switch.md#locking).
+
+```ts
+const TAG = 'pendingJobIds';
+
+async function jobArrived(s: Switch, flowElement: FlowElement, job: Job): Promise<void> {
+  const stored = await s.getGlobalData(Scope.FlowElement, TAG, true);
+  let updated = stored;
+  try {
+    const ids: string[] = stored === '' ? [] : JSON.parse(stored);
+    if (!ids.includes(job.getId())) ids.push(job.getId());
+    updated = JSON.stringify(ids);
+  } finally {
+    await s.setGlobalData(Scope.FlowElement, TAG, updated); // releases the lock, also on error
+  }
+}
+
+async function timerFired(s: Switch, flowElement: FlowElement): Promise<void> {
+  // Take the list and empty it under the lock, then work on the jobs without holding it.
+  const stored = await s.getGlobalData(Scope.FlowElement, TAG, true);
+  await s.setGlobalData(Scope.FlowElement, TAG, '[]'); // releases the lock
+  const ids: string[] = stored === '' ? [] : JSON.parse(stored);
+  if (ids.length === 0) return;
+  const jobs = await flowElement.getJobs(ids);
+  // process and send each job
+}
+```
+
+To track more than one tag, lock them together with the array form of `getGlobalData` and release
+them with one array `setGlobalData`; a second locking call in the same invocation throws. Remove the
+tag in `flowStopTriggered` (global data is never cleaned up automatically), and see the
+[flow restart gotcha](entry-points.md#job-processing) for why `jobArrived` must also skip jobs that
+are already registered.
+
+---
+
+## 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/job.md

@@ -0,0 +1,187 @@
+---
+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`).
+> 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.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Identity
+- Priority
+- File access
+- Routing
+- Failure & logging
+- Child jobs
+- Private data
+- Datasets (metadata)
+- Variables & structured data
+<!-- docs-index:contents end -->
+
+## 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
+// Switch 22.1+
+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. See [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs) for which `sendTo*()` method is appropriate for a given `ConnectionType`/`OutgoingConnections` declaration.
+
+**Routing is applied when the entry point returns.** Each `sendTo*()` call registers a routing action; Switch places all the jobs from one invocation in their output folders together, after it returns. If the entry point throws or is aborted, none of its routing actions reach Switch, including those for jobs routed earlier in the same call. A long `timerFired` that produces many jobs delivers them all at the end; to deliver them sooner, handle fewer items per call and let the timer fire again.
+
+```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. **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>
+```
+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 [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. 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>
+```
+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 [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. `EnfocusSwitchPrivateDataTag` needs Switch 21.0+; before 21.0, store string values only (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)). For each tag's string value (`"EnfocusSwitch.<name>"`) and the release that added it, see [enums.md § EnfocusSwitchPrivateDataTag](enums.md#enfocusswitchprivatedatatag).
+
+```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, JSON, or Opaque) attached to a job. `DatasetModel.JSON` needs Switch 22.0+; read a JSON dataset back with `job.getJSONData()` (24.0+).
+
+```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 after routing — see [job-patterns.md](job-patterns.md#temp-file-cleanup).
+
+```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
+
+Everything in this section needs Switch 24.0+.
+
+```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/logging.md

@@ -0,0 +1,117 @@
+---
+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 [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.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Log levels
+- Don't add a verbosity property
+- Logging in loops
+- `console.log` does not work
+- Don't double-log before a failure
+- Message formatting and the `%` gotcha
+- Signature gotcha: array vs. single value
+- Placeholders instead of concatenation
+- Message quality
+- Log volume
+<!-- docs-index:contents end -->
+
+## 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 [logs-and-dataroot.md](../switch-project/logs-and-dataroot.md#retention-and-the-debug-level-gate). |
+
+## Don't add a verbosity property
+
+Switch already has the switch: `Debug` messages only reach the log database when the preference
+"Log debug messages" is on. A script-level "log detail" or "verbose logging" property duplicates a
+control the user already has, adds a row to the property pane, and (for an app) adds strings to
+translate. Put verbose detail behind `LogLevel.Debug` and let the preference govern it.
+
+## 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
+[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.
+
+## 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.
+
+## 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.