Download File

Summary

Internal name: DownloadTask
Category: Communication
Purpose: Download a file from a remote URL to a local path on the Android device 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
- WRITE_EXTERNAL_STORAGE

Detailed description

The Download File task opens an HTTP or HTTPS connection to the remote url and streams the response body to the local file at path, using OkHttp via FileTransferClient.downloadToFile(). The operation runs asynchronously and waits for a callback. Progress is logged as bytes/totalBytes in the task report.

Both url and path 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 URL — supports `$variable`	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	`""`
`path`	String	Yes	Absolute local path (e.g. `/sdcard/Downloads/file.zip`) — 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 — downloaded 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).

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 download failure.
Timeout	Timeout	`AndromateTimeoutException` — the operation exceeded `timeout_ms`. No specific exception code.

Execution flowchart

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

    ResolveParams --> CallClient[🌐 FileTransferClient.downloadToFile\nOkHttp — async]

    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.downloadToFile() via OkHttp — the call is 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 — Download a file with default timeout

{
  "DownloadTask": [
    {
      "id": "1",
      "title": "Download firmware package",
      "url": "https://example.com/firmware.zip",
      "path": "/sdcard/Downloads/firmware.zip",
      "file_size_output": "$downloaded_bytes",
      "duration_ms_output": "$download_duration_ms",
      "bitrate_output": "$download_bitrate"
    }
  ]
}

Example 2 — Download using workflow variables

{
  "DownloadTask": [
    {
      "id": "2",
      "title": "Download dynamic target",
      "url": "$remote_url",
      "path": "$local_path",
      "file_size_output": "$file_size",
      "duration_ms_output": "$dl_time",
      "bitrate_output": "$dl_bitrate"
    }
  ]
}

Example 3 — Download with custom timeout

{
  "DownloadTask": [
    {
      "id": "3",
      "title": "Download with 30s timeout",
      "url": "https://example.com/large-dataset.csv",
      "path": "/sdcard/data/dataset.csv",
      "timeout_ms": 30000,
      "file_size_output": "$csv_size",
      "duration_ms_output": "$csv_dl_ms",
      "bitrate_output": "$csv_bitrate"
    }
  ]
}

Example 4 — Download and measure transfer speed

{
  "DownloadTask": [
    {
      "id": "4",
      "title": "Download speed test",
      "url": "https://example.com/testfile.bin",
      "path": "/sdcard/Downloads/testfile.bin",
      "timeout_ms": 15000,
      "file_size_output": "$bytes_received",
      "duration_ms_output": "$elapsed_ms",
      "bitrate_output": "$speed_bps"
    }
  ]
}

Input parameter details

1. `url` — Remote file URL

The full HTTP or HTTPS URL of the remote resource to download. Must be a non-empty, well-formed URL including the scheme (http:// or https://).

Supports $workflow_variable references — resolved at runtime before the transfer starts.

Valid	Invalid
`https://example.com/file.zip`	`file.zip` (no scheme)
`http://192.168.1.1/data.bin`	`ftp://example.com/file` (unsupported scheme)
`$remote_url`	`""` (empty)

Default: ""

2. `path` — Local destination path

The absolute path on the Android device where the downloaded file will be saved. The parent directory must exist and the application must have write access to it.

Must be absolute: paths not starting with / are not valid
Parent directory must exist: the task does not create missing intermediate directories
Supports variables: Yes — e.g. /sdcard/$filename
Default: ""

3. `timeout_ms` — Operation timeout

Maximum time in milliseconds allowed for the entire download operation (including connection and data transfer). If exceeded, an AndromateTimeoutException is thrown.

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

Output parameter details

`file_size_output` — Downloaded file size

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

Written only on successful completion
Value is the byte count of the written file (e.g. 204800 for 200 KB)

`duration_ms_output` — Transfer duration

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

Measured from the moment the transfer starts to when the last byte is written to disk

`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 throughput reporting

Complete JSON example

{
  "DownloadTask": [
    {
      "id": "1",
      "title": "Download test file",
      "url": "https://speed.example.com/10mb.bin",
      "path": "/sdcard/Download/10mb.bin",
      "timeout_ms": 30000,
      "file_size_output": "$dl_bytes",
      "duration_ms_output": "$dl_time_ms",
      "bitrate_output": "$dl_bitrate_bps"
    }
  ]
}