Upload File

Summary

Internal name: UploadTask
Category: Communication
Purpose: Upload a local file from the Android device to a remote server via HTTP multipart upload and report transfer statistics.
Task type: Normal

Compatibility

Minimum AndroMate version: 1.1.0
Maximum AndroMate version: 1.1.0
Minimum Android: Android 13 (API 33)
Maximum Android tested: Android 16 (API 36)
Supported manufacturers:
- ✅ Samsung (One UI 6.x / 7.x / 8.x)
- ✅ Google Pixel (Android Stock)
- ⚠️ Other manufacturers — not tested
Required permissions:
- INTERNET
- ACCESS_NETWORK_STATE
- READ_EXTERNAL_STORAGE

Detailed description

The Upload File task reads a local file from path and uploads it to the remote server at url using HTTP multipart upload via FileTransferClient.uploadMultipart() (OkHttp). The call is asynchronous and waits for a callback. Progress is logged as bytes/totalBytes in the task report.

The path parameter is the local file to upload; url is the server endpoint receiving the file. Both support $workflow_variable references — resolved at runtime before the transfer starts. The operation is bounded by timeout_ms. If the timeout is exceeded, an AndromateTimeoutException is thrown. If the transfer fails for any other reason, exception DOWNLOAD-UPLOAD-ERROR-001 is raised.

On success, the task writes the file size, transfer duration, and bitrate to the three output variables from TransferStatResult.

Input parameters

Parameter	Type	Required	Possible values	Android Compatibility	AndroMate Compatibility	Default
`url`	String	Yes	Valid HTTP/HTTPS server endpoint URL — supports `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`path`	String	Yes	Absolute local file path to upload — supports `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`timeout_ms`	Long	No	Timeout in milliseconds	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`5000`

Output parameters

Field	Type	Trigger condition	Android Compatibility	AndroMate Compatibility	Default
`file_size_output`	Long	Always on success — uploaded file size in bytes	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`
`duration_ms_output`	Long	Always on success — transfer duration in milliseconds	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`
`bitrate_output`	Double	Always on success — transfer bitrate in bytes/second	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`<ANDROMATE_NULL_VALUE>`

Note: Output variables are only written if the corresponding workflow variable already exists in the execution context (declared in the Start task). The outputs are file transfer statistics, not HTTP response data.

Exceptions

Code	Exception Name	Description
`DOWNLOAD-UPLOAD-ERROR-001`	File Transfer Error	A file transfer error occurred (from `AndromateExceptionTypes.FILE_TRANSFER_ERROR`). Raised on any upload failure.
Timeout	Timeout	`AndromateTimeoutException` — the operation exceeded `timeout_ms`. No specific exception code.

Execution flowchart

flowchart TD
    Start([▶ UploadTask]) --> ResolveParams[🔄 Resolve url + path\n+ timeout_ms]

    ResolveParams --> CallClient[🌐 FileTransferClient.uploadMultipart\nOkHttp — async multipart upload]

    CallClient --> WaitCallback[⏳ Wait for async callback]

    WaitCallback -->|timeout_ms exceeded| ETimeout[❌ Timeout\nAndromateTimeoutException]
    WaitCallback -->|Transfer error| E1[❌ DOWNLOAD-UPLOAD-ERROR-001\nFile Transfer Error]
    WaitCallback -->|Success| WriteOutputs[💾 Write TransferStatResult\nfile_size_output\nduration_ms_output\nbitrate_output]

    WriteOutputs --> Success([✅ TransferStatResult])

    ETimeout --> Error([❌ Exception])
    E1 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style ETimeout fill:#ffcdd2
    style E1 fill:#ffcdd2
    style ResolveParams fill:#fff9c4
    style CallClient fill:#f3e5f5
    style WaitCallback fill:#f3e5f5
    style WriteOutputs fill:#c8e6c9

How it works:

Resolve parameters: url, path, and timeout_ms are resolved from the workflow context
Call FileTransferClient: invokes FileTransferClient.uploadMultipart() via OkHttp — HTTP multipart upload, asynchronous
Wait for callback: blocks until the async callback fires or timeout_ms is exceeded
On timeout: throws AndromateTimeoutException
On error: throws DOWNLOAD-UPLOAD-ERROR-001 (file transfer error)
On success: writes file_size_output, duration_ms_output, and bitrate_output from TransferStatResult
Result: returns TransferStatResult

Code examples

Example 1 — Upload a file with default timeout

{
  "UploadTask": [
    {
      "id": "1",
      "title": "Upload report",
      "url": "https://api.example.com/upload",
      "path": "/sdcard/Download/report.json",
      "file_size_output": "$uploaded_bytes",
      "duration_ms_output": "$upload_duration_ms",
      "bitrate_output": "$upload_bitrate"
    }
  ]
}

Example 2 — Upload using workflow variables

{
  "UploadTask": [
    {
      "id": "2",
      "title": "Upload dynamic file",
      "url": "$upload_endpoint",
      "path": "$local_file_path",
      "file_size_output": "$file_size",
      "duration_ms_output": "$upload_time",
      "bitrate_output": "$upload_rate"
    }
  ]
}

Example 3 — Upload with custom timeout

{
  "UploadTask": [
    {
      "id": "3",
      "title": "Upload large file with 60s timeout",
      "url": "https://storage.example.com/results/run1.zip",
      "path": "/sdcard/results/run1.zip",
      "timeout_ms": 60000,
      "file_size_output": "$zip_size",
      "duration_ms_output": "$zip_upload_ms",
      "bitrate_output": "$zip_bitrate"
    }
  ]
}

Input parameter details

1. `url` — Upload endpoint

The HTTP or HTTPS URL of the server endpoint receiving the uploaded file. Supports $workflow_variable references.

Default: ""
Supports variables: Yes

2. `path` — Local file path

The absolute path of the file on the Android device to upload. The file must exist and be readable. This is the local file sent to the server.

Valid	Invalid
`/sdcard/Download/report.json`	`report.json` (relative path)
`/data/local/tmp/test.bin`	`sdcard/test.bin` (no leading `/`)
`$local_file_path`	`""` (empty)

Default: ""
Supports variables: Yes

3. `timeout_ms` — Operation timeout

Maximum time in milliseconds allowed for the entire upload operation. If exceeded, an AndromateTimeoutException is thrown.

Type: Long
Default: 5000 (5 seconds)
For large files: increase to 60000 or higher to avoid premature timeouts

Output parameter details

`file_size_output` — Uploaded file size

Stores the total size of the uploaded file in bytes (Long), from TransferStatResult, in the specified workflow variable.

Written only on successful completion
Value is the byte count of the local file that was uploaded

`duration_ms_output` — Transfer duration

Stores the total elapsed time of the upload operation in milliseconds (Long), from TransferStatResult.

Measured from the moment the transfer starts to completion of the multipart upload

`bitrate_output` — Transfer bitrate

Stores the measured transfer bitrate in bytes per second (Double), from TransferStatResult.

Computed as file_size / (duration_ms / 1000.0)
Useful for network upload throughput reporting

Complete JSON example

{
  "UploadTask": [
    {
      "id": "1",
      "title": "Upload report file",
      "url": "https://api.example.com/upload",
      "path": "/sdcard/Download/report.json",
      "timeout_ms": 30000,
      "file_size_output": "$uploaded_bytes",
      "duration_ms_output": "$upload_ms",
      "bitrate_output": "$upload_bitrate_bps"
    }
  ]
}