Target Filters & Auto-Assignment

A target filter is a saved FIQL query. On its own it’s a convenient, named way to select devices. Attach a distribution set to it, and it becomes an auto-assignment rule: matching targets receive that DS automatically — now, and as new matching devices appear.

Creating a filter

curl -u admin:pw -X POST localhost:8088/rest/v1/targetfilters \
  -H 'Content-Type: application/json' \
  -d '{"name":"beta-ring","query":"controllerId==beta-*"}'

The query is validated against the target field map at write time — an invalid FIQL expression returns 400 Bad Request, and a duplicate name returns 409 Conflict. Update, fetch, list, and delete follow the usual REST shape:

curl -u admin:pw -X PUT    localhost:8088/rest/v1/targetfilters/1 \
  -H 'Content-Type: application/json' -d '{"query":"name==beta-*"}'
curl -u admin:pw           localhost:8088/rest/v1/targetfilters
curl -u admin:pw -X DELETE localhost:8088/rest/v1/targetfilters/1

Attaching an auto-assign distribution set

curl -u admin:pw -X POST localhost:8088/rest/v1/targetfilters/1/autoAssignDS \
  -H 'Content-Type: application/json' \
  -d '{"id":1,"type":"forced"}'

• id — the distribution set to assign. It must be complete (400 otherwise).
• type — forced (default) or soft.

Attaching immediately assigns the DS to every currently-matching target. Read or detach the attachment with:

curl -u admin:pw           localhost:8088/rest/v1/targetfilters/1/autoAssignDS   # -> the DS, or 204
curl -u admin:pw -X DELETE localhost:8088/rest/v1/targetfilters/1/autoAssignDS

From the web console

Everything above is also available under Target filters in the web console:

• New filter / Edit — name plus FIQL query. The query is checked against the live target list as you type, so the form shows how many targets it matches (or the parser’s complaint) before you save; the API’s 400/409 messages are shown against the query and name fields.
• Auto-assign… — pick a distribution set and the action type (forced or soft), or Detach to remove the attachment. An incomplete set is reported inline rather than as a raw failure.
• The Auto-assign column names the attached set, so you can see which filters are live rules at a glance.

When auto-assignment runs

A matching target receives the DS:

• On registration — a device auto-registering via DDI that matches a filter is assigned in the same poll (its very first poll can already return a deploymentBase).
• On attribute change — updating a target via configData re-evaluates the filters.
• Periodically — a background sweep (sharing the rollout evaluator’s task) catches targets created through other paths.

Non-disruptive by design

Auto-assignment never disturbs work in flight. A matching target is skipped if it already has that DS assigned, or if it has any active action. So a device mid-deployment is never clobbered by an auto-assign rule; it’s picked up on a later sweep once it’s idle.

Note: FIQL auto-assignment matches on the standard target fields (controllerId, name, updateStatus, …). Matching on device-reported attributes is not yet supported.