TusAdvancedUpload is a plug-and-play block for uploading files of any size in OutSystems Reactive Web and Mobile apps. It uses the open tus protocol, so uploads are sent in chunks, can be paused and resumed, and recover automatically from network failures or page reloads, continuing from the last byte the server received.
Resumable uploads: interrupted uploads continue where they stopped, even after a page reload.
Pause, resume and abort from OutSystems client actions.
Large-file mode: streams files straight from disk, so multi-GB uploads are possible.
Chunked uploads: optional chunk size for proxies or load balancers with request-size limits.
Validation: maximum file size and allowed file types are checked before the upload starts.
Built-in progress bar and live status, both accessible to screen readers.
Secure download helper: server-side download restricted to your tus server.
A tus server, e.g. tusd (Go), tus-node-server or tusdotnet. It can store files on disk, S3, Azure Blob or Google Cloud Storage.
HTTPS on the tus server in production.
CORS enabled on the tus server for your OutSystems domain, allowing the tus headers (Upload-Offset, Upload-Length, Tus-Resumable, Location).
A dependency on the TusJSClientFileUploader module in your app.
Note: https://tusd.tusdemo.net/files/ is a public demo server for testing only. Files there are public and deleted regularly. Use your own tus server in production.
Add a dependency to TusAdvancedUpload (and, if needed, the client actions and GetFileBy_tusURL) from TusJSClientFileUploader.
Drag the TusAdvancedUpload block onto your screen.
Set UPLOAD_ENDPOINT to your tus server URL.
Optionally set MaxFileSize, accept and Header (for authentication).
For files larger than a few hundred MB, set KeepFileInMemory = False.
Handle the onSuccess event to save upload_url and FileName (for example in your database).
Handle onError to show a message to the user.
To support Pause / Resume / Abort buttons, handle GetUploadObject and store Object in a local variable (see section 7).
Input
Type
Default
Description
UPLOAD_ENDPOINT
Text
"https://tusd.tusdemo.net/files/"
Creation endpoint of your tus server. Use HTTPS in production.
Header
"" (none)
Extra HTTP headers as a JSON object, e.g. {"Authorization": "Bearer <token>"}. Build the value at runtime; never hard-code secrets.
accept
"" (any)
Allowed file types, comma separated, e.g. .pdf,.png,image/*. Applied to the file picker and checked again before upload.
MaxFileSize
Integer
0
Maximum file size in MB. 0 or negative = no limit.
Is_ProgressBar
Boolean
True
Show the built-in progress bar.
Is_LiveStatus
Show the built-in status text.
ChunkSizeMB
New. Size of each upload request in MB. 0 = whole file in one request. Set e.g. 5 to 50 when a proxy limits request size.
AskBeforeResume
False
New. True = ask the user which earlier attempt to resume. False = resume the latest unfinished upload automatically.
KeepFileInMemory
New. True = standard mode (file content returned in onSuccess.File). False = large-file mode (streams from disk; onSuccess.File is empty). See section 6.
Tip: All inputs are optional. Existing screens keep working without changes.
Event
Parameters
When it fires
GetUploadObject
Object (Object)
When an upload starts. Store Object in a local variable and pass it to pauseUpload, resumeUpload and abortUpload.
onProgress
percentage (Text)
While uploading, each time the whole percentage changes. Value has 2 decimals, e.g. "42.17". Convert with TextToDecimal().
onSuccess
upload_url (Text), File (Binary Data), FileName (Text)
When the upload completes. upload_url is the file URL on the tus server. File contains the content only when KeepFileInMemory = True.
onError
error (Text)
When validation or the upload fails. error is a readable message (see section 11).
Standard (KeepFileInMemory = True)
Large-file (KeepFileInMemory = False)
File picker
OutSystems Upload widget
Native browser file input
Browser memory
Whole file loaded into memory
Streamed from disk in chunks
Recommended size
Up to a few hundred MB
Large files, including multi-GB
onSuccess.File
Contains the file content
Empty; use upload_url
onSuccess.FileName
Provided
Recommended for large files: KeepFileInMemory = False together with ChunkSizeMB between 5 and 50.
Action
Behaviour
pauseUpload
Pauses the upload. It can be resumed later, even after a page reload, by selecting the same file.
resumeUpload
Continues the upload from the last byte confirmed by the server.
abortUpload
Cancels the upload and asks the server to delete the partial file. It cannot be resumed afterwards.
All three actions take the same inputs:
UploadOBJ
Object
The object received in the GetUploadObject event.
UploadIBlockD
Id of the block instance, e.g. TusAdvancedUpload.Id. Used to update the status text and progress bar.
Create a local variable UploadObject of type Object on the screen.
In the GetUploadObject handler, assign UploadObject = Object.
Add three buttons. Each one calls pauseUpload, resumeUpload or abortUpload with UploadOBJ = UploadObject and UploadIBlockD = TusAdvancedUpload.Id.
Optionally keep an UploadState variable (uploading / paused / done / error) to enable or disable the buttons.
Parameter
URL (input)
The upload_url returned by onSuccess.
Out_Binary (output)
Binary Data
The file content.
Only http:// and https:// URLs are accepted.
When the AllowedDownloadBaseURL site property is set, only URLs that start with it are downloaded.
Disallowed URLs raise the InvalidTusURL user exception.
Important: This action loads the whole file into server memory. Use it for small and medium files. For large files, give the user the tus URL directly, since tus servers such as tusd serve downloads via GET.
Site property
AllowedDownloadBaseURL
Allow-list for GetFileBy_tusURL, e.g. https://tus.example.com/files/. Always end with "/". Empty = only the http/https check (previous behaviour). Set it in every environment.
When Is_LiveStatus = True, the block shows these messages and sets a data-state attribute you can style:
Message
data-state
Meaning
Status: Waiting
idle
No file selected yet.
Status: Preparing upload...
uploading
Upload is starting.
Status: Resuming previous upload...
An earlier attempt was found and is continuing.
Status: Uploading (42.17%)
Upload in progress.
Status: Upload paused
paused
pauseUpload was called.
Status: Upload complete ✅
success
Upload finished.
Status: Upload cancelled ❌
cancelled
abortUpload was called.
Status: Upload failed: …
error
See section 11.
The block uses OutSystems UI tokens, so it follows your app theme. Override these classes in your theme to customise it:
CSS class
Element
.tus-upload
Upload widget (standard mode).
.tus-native-input
File input in large-file mode.
.tus-progress / .progress-container
Progress bar track.
.tus-progress-bar / .progress-bar-grv
Progress bar fill.
.tus-status
Status text. Use [data-state=...] for state colours.
The older class names .progress-container and .progress-bar-grv are still supported.
error value
Cause
Upload failed: File Size exceeded
File is larger than MaxFileSize.
Upload failed: File type not allowed
File does not match accept.
Upload failed: invalid Header configuration
Header is not a valid JSON object.
Upload failed: no upload endpoint configured
UPLOAD_ENDPOINT is empty.
Upload failed: this browser does not support resumable uploads
Very old browser or tus library not loaded.
Upload failed: <details>
Network, server or authentication error returned by the tus server.
Use HTTPS for the tus endpoint.
Pass authentication tokens through Header, built at runtime (never hard-coded).
Set AllowedDownloadBaseURL in every environment.
Validate file size and type again on the server. Browser checks can be bypassed.
Restrict CORS on the tus server to your own domains.
Store only the upload_url and metadata in your database; keep files in the tus storage.
Problem
Solution
CORS error in the browser console
Enable CORS on the tus server for your domain and expose the tus headers.
413 Request Entity Too Large
Set ChunkSizeMB (e.g. 5) or raise the proxy request-size limit.
Browser slows down or crashes on big files
Set KeepFileInMemory = False.
Upload starts from 0% instead of resuming
Select exactly the same file. Resume information is stored in the browser, so it does not carry over to other browsers or devices.
InvalidTusURL exception
The URL is not http(s) or is outside AllowedDownloadBaseURL.
401 / 403 from the tus server
Check the token in Header.
Backward compatible: no inputs, events or actions were renamed or removed.
Automatic resume replaces the browser prompt. Set AskBeforeResume = True to keep the prompt.
The default Header is now empty (the dummy Authorization header was removed).
MaxFileSize is now optional; 0 means no limit.
onProgress now fires on whole-percent changes instead of every chunk.
Set the new AllowedDownloadBaseURL site property.
TusAdvancedUpload is a plug-and-play web block for uploading large files in OutSystems Reactive or Mobile apps using the tus.io resumable upload protocol. This component enables chunked, pause-resume, and recoverable uploads, with a simple OutSystems interface and minimal setup.
Drag the TusAdvancedUpload block to your screen.
TusAdvancedUpload
Pass the required inputs like MaxFileSize.
Define logic in event actions (onSuccess, GetUploadObject, etc.).
Optionally, call GetFileBy_tusURL In an action to retrieve the uploaded file’s binary data.
GetFileBy_tusURL
image/*
.pdf
upload