Skip to main content
Version: 2.5.0

SMB / CIFS Nodes

SMB nodes connect a MaestroHub pipeline to a remote Windows or Samba file share over SMB/CIFS. Use them to ingest file drops, export daily reports, archive processed files, and discover what files are available without leaving the pipeline canvas. All five nodes are backed by SMB connections and functions.

Configuration Quick Reference​

FieldWhat you chooseDetails
ParametersConnection, Function, Function Parameters, Timeout OverrideSelect the SMB connection, the function (Fetch / Write / List / Delete / Move), configure function parameters (with expression support), and optionally override the timeout.
SettingsDescription, Timeout (seconds), Retry on Timeout, Retry on Fail, On ErrorNode description, max execution time, retry behavior on timeout / failure, and error handling. Defaults inherit from the pipeline.

Every node wraps the function output in a consistent envelope:

{
  "success": true,
  "functionId": "<function-uuid>",
  "data": { /* function-specific payload, see below */ },
  "durationMs": 156000000,
  "timestamp": "2026-01-15T08:30:00Z"
}
FieldTypeDescription
successbooleantrue when the function executed without errors. On failure the node returns an error result and success is false.
functionIdstringID of the SMB function that was executed (the saved function on the connection, not the function type).
dataobjectFunction‑specific payload. The shape differs by node type — see each section below.
durationMsnumberFunction execution duration (the connector's internal duration, in nanoseconds; divide by 1,000,000 for milliseconds).
timestampstringRFC 3339 / ISO 8601 UTC timestamp of when the node emitted the result.

SMB Fetch File​

SMB Fetch File node configuration

SMB Fetch File Node

Read a file from the share — by literal name, glob, or regex; optionally recursive.

Supported Function Types:

Function NamePurposeCommon Use Cases
Fetch FileRead a file from the SMB shareIngest CSV/JSON drops, fetch reports, locate files by name across subfolders

Node Configuration​

ParameterTypeRequiredDescription
ConnectionSelectionYesSMB connection profile to use
FunctionSelectionYesA smb.fetch.file function defined on the selected connection
Function ParametersDynamicVariesAuto‑populated from the function schema (fileName, recursive, outputFormat, timeoutMs, maxFileSizeMB, discoveryLimit). See SMB connection functions for parameter details.
Timeout OverrideNumber (seconds)NoOverride the function's default timeout

All function parameters support expression syntax ({{ expression }}) — e.g., {{ $input.data.files[0].name }} to fetch a file the previous node picked.

Input​

The node receives the previous node's output as $input. Reference upstream data inside function parameters with expressions.

Output Structure​

{
  "success": true,
  "functionId": "fn_smb_fetch_inbound",
  "data": {
    "data": "aWQsbmFtZSx2YWx1ZQoxLGFscGhhLDEwMAo...",
    "metadata": {
      "fileName": "data_2026-01-15.csv",
      "filePath": "inbound/data_2026-01-15.csv",
      "fileType": "csv",
      "sizeBytes": 2048,
      "lastModified": "2026-01-15T08:30:00Z",
      "discoveryPattern": "data_*.csv",
      "outputFormat": "base64"
    }
  },
  "durationMs": 156000000,
  "timestamp": "2026-01-15T08:30:00Z"
}

Fetch Result Fields​

FieldTypeDescription
data.datastringFile content. Base64‑encoded when outputFormat=base64 (default), raw UTF‑8 string when outputFormat=text. With text and a UTF‑8 BOM source, the BOM is stripped automatically.
data.metadata.fileNamestringBasename of the resolved file.
data.metadata.filePathstringShare‑relative path of the resolved file.
data.metadata.fileTypestringExtension without the leading dot (csv, json, …). Empty when the file has no extension.
data.metadata.sizeBytesnumberFile size in bytes.
data.metadata.lastModifiedstringRFC 3339 / ISO 8601 UTC timestamp of last modification.
data.metadata.discoveryPatternstringEffective pattern used (the literal name or compiled regex). Useful for debugging templated fileNames.
data.metadata.outputFormatstringbase64 or text — echoes the request.
data.metadata.encodingHintstringOptional. Present when a BOM was detected: utf-8-bom, utf-16le-bom, utf-16be-bom. Absent otherwise.
Feeding the File Extractor

The SMB Fetch node puts the file content at data.data. When piping into a File Extractor node, set its Input Field to data.data (not the default data).

SMB Write File​

SMB Write File node configuration

SMB Write File Node

Write content to the share — create, overwrite, or append, with encoding control. Non‑append writes are atomic (temp file + rename), so concurrent readers always see either the old file or the new file.

Supported Function Types:

Function NamePurposeCommon Use Cases
Write FileCreate / overwrite / append a file on the shareCSV exports, log appends, dropping JSON metadata next to binaries

Node Configuration​

ParameterTypeRequiredDescription
ConnectionSelectionYesSMB connection profile to use
FunctionSelectionYesA smb.write.file function defined on the selected connection
Function ParametersDynamicVariesAuto‑populated from the function schema (fileName, data, createFile, appendToFile, appendNewline, overwriteExisting, encoding, timeoutMs, maxFileSizeMB). See SMB connection functions for parameter details.
Timeout OverrideNumber (seconds)NoOverride the function's default timeout

Input​

The node receives the previous node's output as $input. Use expressions to source content (e.g., {{ $input.data.csv }}) and file paths (e.g., {{ '/exports/' + ($execution.startedAt | date: 'YYYY-MM-DD') + '/orders.csv' }}).

Output Structure​

{
  "success": true,
  "functionId": "fn_smb_write_export",
  "data": {
    "filePath": "inbound/output/2026-01-15/orders.csv",
    "bytesWritten": 4096,
    "encoding": "utf-8",
    "created": true,
    "appended": false,
    "duration": 87
  },
  "durationMs": 89000000,
  "timestamp": "2026-01-15T08:30:00Z"
}

Write Result Fields​

FieldTypeDescription
data.filePathstringPath actually written. May differ from the input when Overwrite Existing is off and a timestamped variant was written instead.
data.bytesWrittennumberBytes written after encoding transformation (UTF‑16 strings are larger than UTF‑8).
data.encodingstringEncoding actually applied. When the function used auto, this reveals the encoding the connector picked.
data.createdbooleantrue if the file did not exist before this call.
data.appendedbooleantrue if the call appended (rather than wrote whole).
data.durationnumberServer‑side write duration in milliseconds.

SMB List Directory​

SMB List Directory node configuration

SMB List Directory Node

Enumerate files and folders under a path on the share, optionally recursive and pattern‑filtered. The natural source for a For‑Each loop.

Supported Function Types:

Function NamePurposeCommon Use Cases
List DirectoryList entries in a directoryDiscover new files to process, inventory drop folders, confirm uploads

Node Configuration​

ParameterTypeRequiredDescription
ConnectionSelectionYesSMB connection profile to use
FunctionSelectionYesA smb.list.directory function defined on the selected connection
Function ParametersDynamicVariesAuto‑populated from the function schema (path, pattern, recursive, timeoutMs). See SMB connection functions for parameter details.
Timeout OverrideNumber (seconds)NoOverride the function's default timeout

Input​

The node receives the previous node's output as $input. Use expressions to drive the directory path (e.g., {{ '/inbound/' + $input.data.partner }}) or the pattern.

Output Structure​

{
  "success": true,
  "functionId": "fn_smb_list_inbound",
  "data": {
    "path": "/",
    "count": 2,
    "files": [
      {
        "name": "data_2026-01-15.csv",
        "path": "inbound/data_2026-01-15.csv",
        "size": 2048,
        "isDir": false,
        "modified": "2026-01-15T08:30:00Z"
      },
      {
        "name": "archive",
        "path": "inbound/archive",
        "size": 0,
        "isDir": true,
        "modified": "2026-01-14T12:00:00Z"
      }
    ]
  },
  "durationMs": 42000000,
  "timestamp": "2026-01-15T08:30:00Z"
}

List Result Fields​

FieldTypeDescription
data.pathstringDirectory that was listed, relative to the connection's Base Path. / means Base Path root.
data.countnumberNumber of entries returned (after the pattern filter).
data.filesarrayList of file / directory entries.

File Entry Fields​

FieldTypeDescription
namestringBasename of the entry.
pathstringShare‑relative path of the entry (useful as input to a Fetch / Move / Delete node).
sizenumberFile size in bytes; 0 for directories.
isDirbooleantrue if the entry is a directory.
modifiedstringRFC 3339 / ISO 8601 UTC timestamp of last modification.
Drive a For‑Each loop

Wire SMB List Directory into a For Each Loop bound to data.files. Each iteration receives one entry and can branch on isDir.

SMB Delete File​

SMB Delete File node configuration

SMB Delete File Node

Delete a single file from the share. Directories are not supported by design — use Move into a "trash" folder if you need batch cleanup.

Supported Function Types:

Function NamePurposeCommon Use Cases
Delete FileRemove a file from the shareClean up after processing, remove temp / staging files

Node Configuration​

ParameterTypeRequiredDescription
ConnectionSelectionYesSMB connection profile to use
FunctionSelectionYesA smb.delete.file function defined on the selected connection
Function ParametersDynamicVariesAuto‑populated from the function schema (fileName, timeoutMs). See SMB connection functions for parameter details.
Timeout OverrideNumber (seconds)NoOverride the function's default timeout

Input​

The node receives the previous node's output as $input. Use {{ $input.data.metadata.filePath }} to delete a file an earlier Fetch node returned, or {{ $input.data.files[0].path }} after a List.

Output Structure​

{
  "success": true,
  "functionId": "fn_smb_delete_processed",
  "data": {
    "filePath": "inbound/processed/old.csv",
    "deleted": true
  },
  "durationMs": 23000000,
  "timestamp": "2026-01-15T08:30:00Z"
}

Delete Result Fields​

FieldTypeDescription
data.filePathstringShare‑relative path of the deleted file.
data.deletedbooleanAlways true on success.

SMB Move File​

SMB Move File node configuration

SMB Move File Node

Rename or move a file inside the share. The rename is server‑atomic within one share — readers either see the file at the source or the destination, never neither.

Supported Function Types:

Function NamePurposeCommon Use Cases
Move/Rename FileMove or rename a file within the shareRotate inbound/ → processed/, rename a download in place

Node Configuration​

ParameterTypeRequiredDescription
ConnectionSelectionYesSMB connection profile to use
FunctionSelectionYesA smb.move.file function defined on the selected connection
Function ParametersDynamicVariesAuto‑populated from the function schema (sourcePath, destinationPath, overwrite, timeoutMs). See SMB connection functions for parameter details.
Timeout OverrideNumber (seconds)NoOverride the function's default timeout

Input​

The node receives the previous node's output as $input. Most commonly, Source Path is bound to {{ $input.data.metadata.filePath }} from an upstream Fetch, and Destination Path is templated with a date / partner from the execution context.

Output Structure​

{
  "success": true,
  "functionId": "fn_smb_archive_processed",
  "data": {
    "sourcePath": "inbound/orders.csv",
    "destinationPath": "inbound/processed/2026-01-15/orders.csv",
    "moved": true
  },
  "durationMs": 31000000,
  "timestamp": "2026-01-15T08:30:00Z"
}

Move Result Fields​

FieldTypeDescription
data.sourcePathstringResolved source path (share‑relative).
data.destinationPathstringResolved destination path (share‑relative).
data.movedbooleanAlways true on success.
Same share only

Source and destination must both resolve under the connection's Base Path. To move across shares, use Fetch + Write + Delete instead.

Common Use Cases​

Ingest a File Drop​

A partner / PLC / MES drops CSV files onto the share. The pipeline lists, parses, publishes, and archives:

  1. SMB List with pattern *.csv to discover today's drops.
  2. For Each over data.files.
  3. SMB Fetch with fileName = {{ $loop.item.name }}.
  4. File Extractor (with inputField = data.data) to parse the CSV.
  5. MQTT Publish / UNS Publish / wherever the data needs to go.
  6. SMB Move with sourcePath = {{ $loop.item.path }} and destinationPath = processed/{{ $execution.startedAt | date: 'YYYY-MM-DD' }}/{{ $loop.item.name }}.
[Schedule] → [SMB List] → [For Each] → [SMB Fetch] → [File Extractor] → [UNS Publish] → [SMB Move]

Daily Export​

Aggregate today's data, format it as CSV, and drop it on a partner share:

[Schedule] → [SQL Query] → [Data Serializer (CSV)] → [SMB Write]

For the SMB Write node:

  • fileName = {{ '/exports/' + ($execution.startedAt | date: 'YYYY-MM-DD') + '/orders.csv' }}
  • data = {{ $input.data.csv }}
  • createFile = true
  • overwriteExisting = true

Find a File Anywhere​

The drop folder layout isn't predictable — files appear under arbitrary subdirectories. SMB Fetch with Recursive finds them by name:

  • fileName = {{ $input.report.name }}
  • recursive = true

The connector walks the tree under Base Path and returns the first file whose basename matches.

Cleanup After Processing​

After a successful step, archive instead of deleting so audit can trace it:

[Process] → [SMB Move (inbound/file → archive/((date))/file)]

Or, when retention is short and storage is tight, delete:

[Process] → [SMB Delete (processed/((fileName)))]

Settings Tab​

All SMB node types share the same Settings tab:

SettingTypeDefaultDescription
DescriptionText—Optional description shown on the node.
Timeout (seconds)NumberPipeline defaultMaximum time the node may run before timing out.
Retry on TimeoutTogglePipeline defaultAutomatically retry the node if it times out.
Retry on FailTogglePipeline defaultAutomatically retry the node if the function returns an error.
On ErrorSelectionPipeline defaultError strategy: stop the pipeline, continue to the next node, or follow the error output path.

When left at their defaults, these settings inherit from the pipeline‑level execution configuration.

Integration with Other Nodes​

File Extractor​

The most common downstream of SMB Fetch is the File Extractor node, which parses CSV / Excel content into structured rows.

The SMB Fetch node returns the file content at data.data (the outer data is the function envelope; the inner data is the byte payload). Set the File Extractor's Input Field accordingly:

If you are fetchingSet File Extractor's inputField toAnd outputFormat to
CSV with outputFormat=base64 (default)data.database64 input is auto‑decoded
CSV with outputFormat=textdata.datatext input is taken verbatim
Exceldata.data (base64)base64 is required for binary
Size cap

Both SMB Fetch and File Extractor enforce a maximum file size — by default 25 MB on the connector and 256 MB on the File Extractor. If you raise the connector cap above the extractor's, the extractor will reject the file even though the fetch succeeded.

For Each Loop​

Use For Each Loop to process every entry from a list:

  1. SMB List returns data.files — an array of entries.
  2. For Each Loop iterates over data.files.
  3. Each iteration exposes $loop.item with name, path, size, isDir, modified.

A guard inside the loop on $loop.item.isDir keeps directories out of file‑only steps.

Data Serializer​

Use Data Serializer before SMB Write to turn structured data into CSV / JSON / XML:

[SQL Query] → [Data Serializer] → [SMB Write]

The Data Serializer's output becomes the data parameter of the SMB Write node.

Best Practices​

  • Scope Base Path narrowly. A connection with basePath=inbound cannot accidentally read or write C:\Windows\… even with a buggy template.
  • Use literal filenames when you can. Literal names skip the directory walk entirely — they're an order of magnitude faster than glob / regex on large shares.
  • Use Recursive + bare names sparingly. Recursive walks scale with directory size; on a share with 100k files, a recursive Fetch may need to scan thousands of entries before finding a match. Lower Discovery Limit to fail loud instead of slow.
  • Set realistic timeouts. Default 60 s is fine for normal CSV; long Excel or wildcard‑heavy patterns deserve a higher per‑call Timeout Override so a slow file doesn't break the pipeline.
  • Move, don't delete. Archive processed files into processed/<date>/<name> so reruns and audits can still trace what happened.
  • Enable Require Message Signing on every share — modern Samba and Windows servers support it out of the box, and it cheaply blocks on-path tampering. For confidentiality (the share carries personal data or credentials) put the connector and the server on a trusted network: a VPN, IPsec tunnel, or segmented VLAN. Wire-level encryption is not yet enforceable from the connector.
  • Tune Idle Reconnect. If your Windows server kills idle sessions aggressively (≤ 10 min), drop Idle Reconnect Threshold below the server's timeout so the connector re‑mounts before the next call.
Retry configuration

For unreliable WAN links to a share, enable Retry on Timeout and Retry on Fail on each SMB node. The connector itself reconnects silently after long idle periods, but transient network blips still need pipeline‑level retry to recover cleanly.