Tooling
Import gates and dynamic configs
On this page
The file
One JSON file with the objects as the console API (v1) answers them. Each list may be the bare array or the list answer itself ({ message, data: [...], pagination }). A single list answer that holds gates and dynamic configs is accepted too (a dynamic config is recognised by its defaultValue). The format is detected automatically; in the import dialog choose the source that names gates, dynamic configs and segments.
{
"environments": [{ "name": "development" }, { "name": "staging" }, { "name": "production" }],
"gates": { "data": [
{
"id": "new_checkout", "name": "New checkout", "idType": "userID", "isEnabled": true,
"rules": [
{ "id": "r_emp", "name": "Employees", "passPercentage": 100, "environments": null,
"conditions": [{ "type": "email", "operator": "str_contains_any", "targetValue": ["@example.com"] }] },
{ "id": "r_beta", "name": "Beta testers", "passPercentage": 100, "environments": null,
"conditions": [{ "type": "passes_segment", "targetValue": "beta_testers" }] },
{ "id": "r_prod", "name": "Production rollout", "passPercentage": 25, "environments": ["production"],
"conditions": [{ "type": "public" }] }
]
}
] },
"dynamicConfigs": [
{
"id": "pricing", "isEnabled": true, "defaultValue": { "price": 10, "currency": "USD" },
"rules": [
{ "id": "r_tier", "name": "Retail tier", "passPercentage": 100, "environments": null,
"conditions": [{ "type": "custom_field", "field": "tier", "operator": "any_case_sensitive", "targetValue": ["retail"] }],
"returnValue": { "price": 8, "currency": "USD" } }
]
}
],
"segments": [
{ "id": "beta_testers", "type": "id_list", "idType": "userID", "ids": ["u1", "u2"] }
]
}| Field | Meaning |
|---|---|
environments | Environment names (strings or objects with name). Each becomes a source environment you map to one of the project's. Without it, the environments named in rules are used, or a single production. |
gates | Feature gates: id, name, description, idType, isEnabled, type (PERMANENT / TEMPORARY), rules. |
dynamicConfigs | Dynamic configs: as gates, plus defaultValue and a returnValue per rule. |
segments | Segments: type rule_based (with rules) or id_list (with ids, from the segment's ID list endpoint). |
experiments, layers | Optional. Listed in the report as not imported (see below). |
# One answer per list endpoint (page through each list with page=…), then combine them:
jq -n --slurpfile g gates.json --slurpfile c dynamic_configs.json --slurpfile s segments.json \
--slurpfile e environments.json \
'{ environments: $e[0], gates: $g[0], dynamicConfigs: $c[0], segments: $s[0] }' > export.jsonFeature gates
Rules are evaluated in order and the first rule whose conditions all pass decides, as in NanoFlags. A rule's pass percentage decides whether the context gets true; contexts that match the conditions but fall outside the percentage get false and do not try later rules. That maps exactly to NanoFlags rules:
| Source | NanoFlags |
|---|---|
| Gate | Boolean flag; default and off value false. type PERMANENT / TEMPORARY sets the flag's permanent marker. |
| isEnabled: false | The flag is switched off (serves false) in every mapped environment. |
| passPercentage 100 | Rule serving true. |
| passPercentage 0 | Rule serving false (it still stops evaluation, as in the source). |
| passPercentage between | Rollout rule: that percentage gets true, the rest false. Bucketing uses the gate's idType: userID → key, any other unit type → the attribute of that name. |
rule.environments | The rule is imported into those environments only; null means every environment. |
Dynamic configs
- A dynamic config becomes a json flag (purpose operational).
defaultValueis the default and the off value. - Each rule serves its
returnValue; with a pass percentage below 100 it becomes a rollout of the return value against the default value. - Disabled configs are imported switched off (they serve the default value).
Segments
- ID list segments become a segment with
key in [...](or the unit type's attribute). Withoutidsin the file, the segment is imported matching nobody and reported. - Rule-based segments match when any rule matches; each rule's conditions are combined with all. Rules with a pass percentage below 100 are left out and reported (NanoFlags segments have no percentages).
- Segments may reference other segments; nested groups become importer-created segments, as for every source.
Conditions
| Condition type | NanoFlags attribute |
|---|---|
public | Always true (a rule with no conditions). |
user_id | key |
email, country, locale, ip_address, app_version | email, country, locale, ip, appVersion |
browser_name, browser_version, os_name, os_version, device_model | browserName, browserVersion, osName, osVersion, deviceModel. The source can derive these (and country) from the user agent or IP address; NanoFlags reads them only when your application passes them. |
custom_field | The attribute named in field. |
unit_id | The attribute of the unit type named in customID (userID → key, companyID → companyID). |
environment_tier | Resolved per environment while importing: the rule is kept or dropped in each mapped environment. |
passes_segment, fails_segment | segment / not_segment |
| Operator | NanoFlags | Notes |
|---|---|---|
any, none | in / not in | The source compares strings case-insensitively; NanoFlags compares exactly (reported). The source compares values as text, so each value is imported in both forms (5 and "5"). none also matches a missing attribute, as in the source. |
any_case_sensitive, none_case_sensitive | in / not in | Exact; numbers are imported in both forms, as for any. |
str_contains_any, str_contains_none | contains | Case-insensitive in the source (reported). The source also searches numbers as text; NanoFlags searches text attributes only (reported when a value is a number). |
gt, gte, lt, lte | gt gte lt lte | Numbers only. |
eq, neq | eq / neq | The source's loose equality is kept by importing both forms (5 equals "5"). neq also matches a missing attribute. |
is_null, is_not_null | not_exists / exists | Exact. |
What is reported
Nothing is dropped silently: each of these appears in the dry run's warnings with the flag, segment or environment it concerns.
| Source feature | What happens |
|---|---|
| passes_gate / fails_gate conditions | Unsupported: NanoFlags flags do not depend on other flags. The rule is left out. |
| Version, date and regular-expression operators, array operators, time and target-app conditions | Unsupported: the rule is left out. |
| Holdouts | Unsupported: held-out contexts get the normal value. |
| Target apps | Info: not imported; use the flag's client exposure and SDK keys. |
| Segment rules below 100 % | Unsupported: the rule is left out of the segment. |
| ID-list segments without IDs | Unsupported: imported matching nobody. |
| Experiments and layers | Not imported. Their allocation, groups and results stay in the source; recreate them as NanoFlags experiments (see Experiments). |
| Case-insensitive operators, text search on numbers, derived attributes, percentages | Warnings: imported, but individual contexts may be answered differently. |
Fidelity and side-by-side comparison
For this source the fidelity check re-implements the evaluation of the exported objects (rule order, conditions, segments, gate dependencies, pass percentages with the source's own hashing) and compares it with the NanoFlags engine on the drafts. Contexts decided by a percentage on both sides are compared as shares. It is a re-implementation from the documented semantics, not the source's SDK.
To check your real traffic, export a few hundred representative contexts (JSON Lines, one object per line) and compare them before you switch. Contexts in the shape { userID, email, custom: {...}, customIDs: {...} } are flattened (userID becomes key).
{"userID": "u1"}
{"userID": "u-829", "email": "dana@example.com", "country": "SA", "custom": {"plan": "pro"}}
{"key": "u-830", "country": "AE", "plan": "free"}export NANOFLAGS_API_TOKEN=nf_api_… # scope flags:write
nanoflags import export.json --project shop --dry-run
nanoflags import verify export.json --contexts samples.jsonl --project shop- Every context is evaluated for every imported flag and mapped environment, with the source's semantics and with the drafts this file would produce. Nothing is written, and flags that already exist in the project are compared too (the comparison uses this file's conversion, not the drafts already stored).
- Contexts that would get a different value are listed with both values. Differences decided by a percentage on both sides are counted separately.
- The command exits with 1 when a context differs, when nothing could be compared, or when some flag/environment pairs were left out by the evaluation budget, so it can run in CI until the drafts are published.
The same comparison is available in the Management API: send contexts (at most 1000) with a dry run of POST /api/v1/projects/{project}/imports. See also Moving to NanoFlags.