Configuration Import and Export

FccConfigXmlNames deliberately does not name the fields of <activation>, <speedSetting> or <latencySetting>. FccConfigRecordFields reads them off the record components of FccTestActivationRequest, FccSpeedSettingRequest and FccLatencySettingRequest by reflection — the exact records PUT /FCC/item/details and POST /FCC/item/details already use — both to render them into XML on export and to build a record back from the parsed elements on import.

This is why the XML and the JSON of PUT /FCC/item/details cannot drift into two vocabularies for one set of settings. The consequence worth stating explicitly: a field added to one of those three records appears in the document with no change to this package. A column added to fcc_test_config reaches FccTestActivationRequest because the REST API has to carry it; from there it reaches the XML format automatically, both directions, the same release. A hand-written element list is the second place the field would have to be added, and the one most likely found months later as an imported campaign quietly missing a setting nobody remembered to wire up twice.

The complement is equally deliberate: a field renamed on one of those records is renamed in the document too, in the very next release. That is the honest consequence of deriving the vocabulary rather than an accident — a renamed setting genuinely is a new format for that one field, and formatVersion (formatVersion Is Required: 3 Is Written, 2 and 3 Are Read) exists to let a receiver refuse a document it cannot read instead of silently dropping the value under its old name.

This is what version 2 of the format is. A campaign holds several configurations — see Several Configurations, and Whose Limit Bounds Them — so the document carries one <configuration> element per configuration, each with its own <type>, its own settings block and its own <devices>. In version 1 those three sat directly inside <test>, which is the one-measurement-per-campaign shape the schema no longer has.

<configuration> is the one repeatable element of a <test> and is therefore the one exempt from the declared-more-than-once rule: every other element of a <test> states a single fact about the campaign, and a document stating one of them twice is a file somebody assembled wrongly.

<activation> stays at the <test> level and is NOT repeated, which mirrors the contract rather than flattening anything: the timing knobs — the durations, the retry counts, the WAN timeouts — are stated once per campaign in activation, and the save writes those columns identically to every configuration row. The export takes them from the first configuration, which is the one that always exists.

Each configuration’s fleet is resolved on its own. The reader hands the serials to its sink tagged with the configuration’s position, so a document of three configurations produces three fleets rather than one list of everything — and the fleet ceiling is per configuration too, naming which one overran:

A <test> with no <configuration> at all is refused: it describes no campaign, and answering a form with no configuration would be an operator pressing Save on something the service then refuses, with the file long gone from the screen.

Contract 1.6 added timeBasedDurationSec and timeBasedIntervalSec to FccSpeedSettingRequest, so the document gained <timeBasedDurationSec> and <timeBasedIntervalSec> inside <speedSetting> with no change to this package at all — that is the vocabulary being derived working as intended, and FccConfigRoundTripIT asserts that the freedom was real rather than assumed.

That is also the contrast that makes Version 3: What Version 2 Was Losing worth reading: the fields that got LOST were the ones this package named by hand.

A fully populated campaign was saved, exported, imported and compared field by field against itself. Seven fields did not come back, in two groups, and every one of them had been stored on the exporting installation all along:

Version 3 carries both groups. The recurrence travels as a <reactivation> block, written from FccReactivationRequest by the same reflection as <activation> — so type, repeatEvery, startsOn, ends and reactivationCount are all in it, and a field added to that record will travel with no change here. The configuration’s choice travels as four elements beside its <type>.

The root element must carry formatVersion:

A VERSION-1 DOCUMENT IS REFUSED AS A WHOLE and is not read as a single configuration, although it could be: its <type>, its settings block and its <devices> sit inside <test>, which is exactly one configuration’s worth of content. Reading it that way would mean the reader carrying two shapes of <test>, and a half-applied import is the outcome this format’s strictness exists to prevent.

A DOCUMENT CARRYING BOTH SPELLINGS OF THE RECURRENCE IS REFUSED. <reactivationDays> is version 2’s count and <reactivation> carries that same count as reactivationCount, so a file with both states one fact twice and the two can disagree — which is the situation this format refuses everywhere else rather than picking a winner from. It is the same rule that removed configs[].diagnosticsType from the REST contract (the settings block must match the type).

All of the above are refused before the first <test> is even looked at — readRoot() reads the root and its attribute before nextTest() is ever called — except the both-spellings refusal, which needs the <test> it is in.

Why refuse an unknown version rather than default to the current one. An older service reading a newer document would otherwise read it as its own format and silently drop whatever changed. formatVersion is the seam an incompatible release hangs off; a document from a LATER release carries elements this reader would refuse one at a time, and refusing the file by version says so once.

Each of these is refused by name, not silently ignored, if a hand-edited or future document carries it — see Unknown Elements Are Refused, Not Skipped.

<devices> carries <serial> elements only, read in batches of 1000 and resolved against ftacs.cpe through FccDeviceResolveService.resolveForSave — the identical path PUT /FCC/item/details uses for a sourceType=All configuration (Where the Fleet Comes From). Only the resolved cpeId is kept; the serial, model and protocol of the stored snapshot are re-derived from ftacs.cpe, never trusted from the document.

A serial that matches no device visible to the caller fails the parse with 400/9400, naming the count and the offending serials in the caller’s own spelling — it is resolveForSave’s own rule, raised here rather than at save time so that the operator reads it while looking at the file instead of after filling in a form. This is deliberately not the wizard’s behaviour: `POST /FCC/devices/resolve reports an unmatched serial in notFoundSerials and returns the rest of the fleet, because there the operator is still choosing. A campaign holding 19,000 of the 20,500 serials a document named is a compliance report missing 1,500 subscribers with nothing later to reveal it — and since the save applies the same rule a moment later, accepting a shortened fleet here would only move the refusal to a screen the operator has already filled in.

An absent <devices> element means an empty fleet — the normal case for moving a configuration to an installation with a different device inventory — and is a legal draft, exactly as an empty fleet is on PUT /FCC/item/details.

The ft.fcc.max-devices-per-test fleet ceiling is checked in the serial sink, as the batches are read, and before a single one of them is resolved. FccConfigImportService.requireWithinFleetLimit counts them as they arrive, so a document naming 300 000 serials stops at the batch that crosses the limit rather than issuing roughly 300 IN (…​) queries against the ten-connection, read-only ftacs pool — shared with the device wizard — on its way to being refused. The wording is `FccTestValidator’s, byte for byte, on purpose: a caller must not be able to tell which layer refused, or the two messages would drift apart and one of them would become the one nobody tests.

PUT /FCC/item/import answers the details object — the very body POST /FCC/item/details answers, which is the body PUT /FCC/item/details accepts — and writes nothing. DEV-1381 #13 asked for "the same as PUT /GroupUpdate/groups/import`", and that endpoint does exactly this: `GroupUpdateDetailsService.getGroupFromFile parses the XML and returns GroupUpdateGroupDetailsRequest, the form payload, un-saved. Its screen shows the form and the operator presses Save, which is a different endpoint.

id is null — precisely what the save reads as "create" — and state is NOT_ACTIVE, which is not a state anything is in but the state the save will create. activation.type comes back as Immediately: the document deliberately carries no schedule (What the Format Deliberately Does Not Carry), and answering the parsed null would leave the form’s own radio unset on a screen the operator is about to save.

An element the format deliberately does not have — scheduledAt, state, source, id, legacyUgId, activationCount, cpeId — gets its own message naming why it is absent rather than the generic "unknown element" text, because "unknown element scheduledAt" invites the conclusion that the format is incomplete, when it is deliberate:

Why strictness was chosen over ignoring the unknown element. Skipping it would be the friendlier-looking behaviour, and it is the wrong one for this format. An unknown element is either a typo — in which case the setting the operator meant to set is silently not applied — or a field belonging to a later formatVersion, in which case the campaign would be created with part of the configuration the document actually describes and nothing would say so. Both produce a campaign that measures something other than what the file states, which is the one outcome a compliance product must not have. Silently ignoring an unknown element is also exactly how a document from a later format version gets half-applied by an older service — the failure mode formatVersion and this rule exist together to prevent.

A legacy anchor — source = LEGACY or state = ARCHIVED — is not a configuration at all: the M4 ETL creates it purely to hang imported measurements from (Legacy FCC Import), so it has no fcc_test_config row and no settings row, and its legacy_ug_id points into this installation’s ftacs and means nothing anywhere else. ARCHIVED is also unreachable through evaluate() (fcc_test Transition Table) — nothing this service does ever puts a live campaign there.

Why refused rather than silently skipped, on export in particular. The caller named the id explicitly. A document that quietly holds four of the five campaigns asked for is a document whose missing campaign nobody notices until a compliance run turns out not to exist on the target installation. A silent skip is precisely the failure mode this rule exists to prevent — the same reasoning PUT /FCC/item/details applies to an unresolved cpeId (PUT /FCC/item/details) and FccCatalogService.catalog applies to an empty domain intersection (The Empty Intersection Selects Nothing).

The exported document carries the campaign’s resolved values — what the three-level chain (request, fcc_domain_setting, FT Configs) produced when the operator originally saved the campaign, not the raw request that produced them (The Settings Resolution Chain).

On import those values arrive as explicit request values — level one of the chain on the importing installation — and level one always wins. This is intended, not an oversight: the whole point of export/import is to reproduce a campaign, not to re-derive it against a different installation’s defaults.

The documented way to inherit the target installation’s own defaults is to delete the elements. An operator who wants the target’s per-domain test servers or thresholds removes <downloadUrl>, <uploadUrl> or the latency <testHost> from the file before importing it, because the chain only ever fills a field that is absent (Absent, or blank, means null — and that is load-bearing, not an implementation detail). There is deliberately no flag for this: a flag would have to choose per field, which is exactly what editing the file already does, per field and visibly, with the resulting document readable by anyone who opens it.

The save decides, and the document’s own <domainId> is read and ignored.

It names a domain of the installation that wrote the file, which means nothing here; and since the import creates nothing, there is no landing domain to decide. PUT /FCC/item/details is where a campaign acquires one — from X-FT-Domain-Id under scope LIST, or from the body’s domainId for a super-domain caller (domainId on create) — and the details object this endpoint answers carries no domain field at all.

That is a real simplification over what this page used to describe. The import had its own domain-entitlement table: honour a visible <domainId>, refuse a foreign one with 403/9403 per test, refuse 0 or negative, and refuse an absent one under scope ALL; it had to both judge the domain and construct the identity each upsert was made with, and it judged it before the test’s fleet was resolved so that a refused test did not spend 20 000 serial lookups first. All of that existed because the import wrote rows. It does not.

The device fleet is still resolved against the caller’s whole visible domain set. identity.domainIds() goes to FccDeviceResolveService.resolveForSave unchanged, so a file naming devices of a domain the caller cannot see resolves to nothing visible and is refused — rather than being silently narrowed.

The test’s list of permitted differences is exactly that second row, and it is the only place the exemption is written down — CREATED_BY_THE_SAVE, with the reason beside each entry.

A field edited out of the document before import — most often downloadUrl / uploadUrl / the latency testHost — is the one legitimate way the imported campaign’s stored values differ from the source’s: the settings chain fills it from the importing installation’s own domain default or FT Configs default instead (The Settings Chain, and How to Opt Out of It).

Parse one <test>, resolve its fleet, save it through the ordinary PUT /FCC/item/details path in its own transaction, record its outcome, and move on — whether or not the previous test succeeded.