Document Upload Node
The Document Upload Node facilitates the ingestion and storage of files from various sources into designated destinations within or external to the Mattr platform.
How It Works
Input Resolution: Resolves input from $input (previous node output) or $secret (vault secrets).
Validation: Validates configuration and source/destination combinations.
Source Handling: If source='remoteUrl', streams and downloads the file.
Destination Routing:
conversation: Stores in-memory cache, returns documentId.
storage: Writes to specified path, returns storagePath.
signedUrl: Performs HTTP PUT/POST to the provided URL.
Output Envelope: Builds a uniform output envelope.
Execution Model: Blocking – node returns only after upload completes or fails.
Configuration Schema
destination
'conversation' | 'storage' | 'signedUrl'
✅
Final storage target.
source
'userInput' | 'content' | 'remoteUrl'
✅
How the file is supplied.
fileBase64
string
Cond. (source='content')
Base-64 encoded content.
remoteUrl
string
Cond. (source='remoteUrl')
Pre-signed or public GET URL.
remoteUrlHeaders
object
Optional
Extra headers for remote GET.
supportedFileTypes
array
Optional (source='userInput')
Allowed extensions (e.g., ["pdf"]).
displayMessage
string
Optional (source='userInput')
UI hint.
storagePath
string
Optional (destination='storage')
Folder/key prefix in bucket.
documentId
string
Optional
Force object key / overwrite.
signedUrl
string
Cond. (destination='signedUrl')
Pre-signed PUT/POST URL.
signedUrlMethod
'PUT' | 'POST'
Optional (destination='signedUrl')
Defaults to PUT.
signedUrlHeaders
object
Optional
Extra headers for push.
name
string
Optional
Display label in canvas.
description
string
Optional
Long-form help text.
Output Schema
statusCode
number
✅
HTTP-like status code (200 for success, 400/500 for error).
documentId
string | null
✅
Identifier for downstream nodes. null when destination='signedUrl'.
mimeType
string
✅
MIME type detected (e.g., "application/pdf").
error
string | null
optional
Error message if processing failed; null on success.
Error Handling
All errors populate the error object and set success=false.
VALIDATION_ERROR: Invalid field combos or missing required fields.
DOWNLOAD_FAILED: source='remoteUrl' and HTTP GET fails.
UPLOAD_FAILED: Write to storage or signed URL fails.
UNSUPPORTED_TYPE: User selects file type not in supportedFileTypes.
Single-Node Test API
For testing a node in isolation (e.g., via the UI "Test" button or a dedicated API), the following endpoint is used:
Path: /skill-runtime/workflows/nodes/DocumentUpload/execute
Method: POST
Purpose: Execute one node in isolation.
Request Body :
{
"nodeType": "DOCUMENT_UPLOAD",
"config": { /* refer to configuration schema */ },
"input": { /* becomes $input */ }
}
Security Notes
Use $secret for tokens in remoteUrlHeaders or signedUrlHeaders; they are redacted from logs.
Files in conversation scope follow chat-retention TTL and are encrypted.
Persistent storage inherits bucket IAM from storageId.
Signed-URL push never logs the full URL to prevent leak of write permissions.
Last updated