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 download base + fileName (see [Download base]). 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.

[[Download base]] == Download base (DownloadHttp address + domain folder)

The base a bare fileName is appended to is not the plain DownloadHttp server address. File Management uploads every file into the folder of the domain that owns it (<DownloadHttp address>/<domain folder>/<file name>, where the domain folder is the dotted domain name mapped onto nested directories — parent.child → parent/child/), so the base is:

DownloadHttp address of the file's domain (with parent-domain fallback) + that domain's folder

Two consequences (DEV-2944):

  • The file’s own domain decides the base, not the caller’s and not the device’s. A super-domain file selected by a specific-domain user resolves against the server root, a sub-domain file against the sub-domain folder, and so on. The owning domain is read from the file’s files_ftp.location_id row; when the file is unknown to File Management the caller’s domain is used as a fallback.

  • With domains disabled (IspEnable = 0) the folder is empty and the base is the plain server address, i.e. single-domain installations are unaffected.

Restore (device backups)

Device backups offered by Restore are not File Management files, but they follow the very same layout: Backup / Upload writes them to <UploadHttp address of the device’s domain>/<domain folder>/, so Restore has to read them back from the device’s domain — never from the acting user’s domain and never from the super domain (DEV-2944):

  • the restore-point list is read over FTP from the DownloadFtp server of the device’s domain (with parent-domain fallback), listing that domain’s folder — the cached one-per-client-type FTP client is bound to the domain-0 settings and cannot be used;

  • the download base of a restore point is getDownloadHttpBase(deviceDomainId), i.e. the device domain’s DownloadHttp address plus its folder;

  • the Restore task of Group Update / Automation / Device Profile resolves the same way against the domain of the user who owns the task.

Credentials

The Username / Password sent to the device belong to the URL, not to the request (DEV-2733):

  • Select-from-list / default server — the request carries no credentials (the UI does not ask for them), so the backend attaches the Username / Password configured for the file server the URL was resolved against (DownloadHttp for Download and Software manager, UploadHttp for Upload) - the same server the [Download base] came from, i.e. the one of the domain that owns the file, with the parent-domain fallback. Without this the device receives <Username/><Password/> and cannot fetch a file from a server that requires authorization.

  • Manual enter URL — whatever the operator typed is sent untouched. Request-supplied credentials are never overridden, and a URL that does not start with the configured server address never receives the server credentials.

The same rule applies to the CWMP Download and Upload RPCs, to ChangeDUState (Install / Update in the Software manager tab), and to their USP equivalents.

The rule is enforced on every surface that builds a file-transfer task, not only on the single-device tabs:

Surface Task Credential source

Find device (Download / Upload / Software manager)

Download, Upload, ChangeDUState

The server the URL was resolved against: DownloadHttp of the file’s domain (device domain as fallback, and always the device domain for a Restore point), UploadHttp of the device’s domain (parent-domain fallback)

Device profile — Download files

Download

DownloadHttp of the file’s domain (parent-domain fallback)

Device profile — Set models > backup

Upload

UploadHttp of the profile’s domain (parent-domain fallback)

Group update / Automation — Download, Upload, Install, Update software

Download, Upload, ChangeDUState

DownloadHttp of the file’s domain / UploadHttp of the acting user’s domain (parent-domain fallback)

Group update / Automation — Backup, Restore

Upload, Download

Always the configured UploadHttp / DownloadHttp server — these tasks have no manual URL, so the server credentials are always sent

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