File Download Resolution (url / link / fileName)

Overview

Every surface that triggers a file download on a device (single-device file operations, download tasks in Group Update / Device Profile / Automation, Device Profile files, and Provision) shares one resolution strategy for the fileName, url, and link fields. This page documents that shared behavior, the isManual flag returned on read, and the resetSession / targetLocation request fields introduced for these flows (DEV-2483, DEV-2403).

The backend builds a CpeFileWS and calls the ACS SOAP downloadFiles operation, which in turn issues the TR-069/CWMP Download RPC to the device. See TR-069 Download RPC flow below.

Affected surfaces

Surface Endpoint / entry point fileName field name

Single-device file operation

PUT /iot-webservice/Device/file

fileName

Provision file details

POST /iot-webservice/Device/file/details

fileName

Download task (Group Update)

Group update task action

filename (lowercase — see [Naming inconsistency])

Download task (Device Profile)

Device profile task action

fileName

Download task (Automation)

Automation task action

fileName

Device Profile files

Device profile file entries

fileName

Provision

Provision file resolution

fileName

[[Naming inconsistency]] NOTE: Field names are consistent as fileName, url, link, isManual, resetSession, targetLocation across every surface above except the Group Update task action response, which serializes the resolved file name as filename (lowercase). Consumers of that response must use the lowercase key; do not assume full naming uniformity across surfaces.

Resolution strategy

The backend applies the same three-case resolution to fileName / url / link on every surface listed above:

Case Input Resolution

(a) All empty

fileName, url, and link are all empty/null

The newest firmware for the user’s current domain is used. For download tasks this is the "newest firmware" flag; for Device Profile / single-device flows it resolves to the concrete file with the most recent upload date among the files flagged as newest. This preserves prior behavior.

(b) Select-from-list

Only fileName is provided (url/link are null); isManual=false

The backend builds the URL itself: the domain’s DownloadHttp server address + fileName. This is now applied consistently on all surfaces (previously only the single-device path built the URL this way).

(c) Manual enter URL

url and link are provided; isManual=true

The backend leaves url/link untouched and sends them to the device as given.

isManual (read)

On read, each file-download surface reports an isManual flag computed by one heuristic, shared across all surfaces: a link is reported as manual (isManual=true) when it either

  • does not start with the domain’s DownloadHttp base address, or

  • carries embedded credentials or a size parameter.

Any other link is reported as isManual=false (backend-resolved, select-from-list case).

New request fields: resetSession and targetLocation

Both fields are accepted on every file-download surface listed above (DEV-2483, DEV-2403):

Field Type Behavior

resetSession

boolean, default false

Maps directly to the reset attribute of the TR-069/CWMP Download RPC sent to the device.

targetLocation

string, optional

Reserved — not yet effective. The API accepts and stores the value, but it is not currently delivered to the device: the ACS SOAP interface / WSDL does not yet expose a corresponding field on the downloadFiles operation. Treat it as a placeholder for future ACS/WSDL support. Do not rely on any device-side effect from this field today.

TR-069 Download RPC flow

For the CPE-facing message exchange — how the resolved url and the resetSession value reach the device via the ACS downloadFiles SOAP call and the CWMP Download RPC — see TR-069 Download RPC flow (PlantUML sequence diagram).

Related pages