Skip to content
NanoFlags
Start free

Tooling

Import gates and dynamic configs

Import feature gates, dynamic configs and segments from a console API export into a project's drafts. Gates become boolean flags, dynamic configs become json flags, segments stay segments; every rule is converted per environment, and anything that cannot be expressed is reported. The general steps (dry run, environment mapping, conflicts) are in Import flags.

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.

export.json
{
  "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"] }
  ]
}
FieldMeaning
environmentsEnvironment 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.
gatesFeature gates: id, name, description, idType, isEnabled, type (PERMANENT / TEMPORARY), rules.
dynamicConfigsDynamic configs: as gates, plus defaultValue and a returnValue per rule.
segmentsSegments: type rule_based (with rules) or id_list (with ids, from the segment's ID list endpoint).
experiments, layersOptional. Listed in the report as not imported (see below).
Assemble the file
# 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.json

Feature 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:

SourceNanoFlags
GateBoolean flag; default and off value false. type PERMANENT / TEMPORARY sets the flag's permanent marker.
isEnabled: falseThe flag is switched off (serves false) in every mapped environment.
passPercentage 100Rule serving true.
passPercentage 0Rule serving false (it still stops evaluation, as in the source).
passPercentage betweenRollout 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.environmentsThe rule is imported into those environments only; null means every environment.
Percentages move individual users
NanoFlags buckets with its own hash, seeded with the flag key. The percentage is kept, but a given user can land on the other side after the move. Plan the switch for flags where that matters (for example, finish a rollout at 0 % or 100 % first).

Dynamic configs

  • A dynamic config becomes a json flag (purpose operational). defaultValue is 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). Without ids in 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 typeNanoFlags attribute
publicAlways true (a rule with no conditions).
user_idkey
email, country, locale, ip_address, app_versionemail, country, locale, ip, appVersion
browser_name, browser_version, os_name, os_version, device_modelbrowserName, 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_fieldThe attribute named in field.
unit_idThe attribute of the unit type named in customID (userID → key, companyID → companyID).
environment_tierResolved per environment while importing: the rule is kept or dropped in each mapped environment.
passes_segment, fails_segmentsegment / not_segment
OperatorNanoFlagsNotes
any, nonein / not inThe 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_sensitivein / not inExact; numbers are imported in both forms, as for any.
str_contains_any, str_contains_nonecontainsCase-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, ltegt gte lt lteNumbers only.
eq, neqeq / neqThe source's loose equality is kept by importing both forms (5 equals "5"). neq also matches a missing attribute.
is_null, is_not_nullnot_exists / existsExact.

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 featureWhat happens
passes_gate / fails_gate conditionsUnsupported: 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 conditionsUnsupported: the rule is left out.
HoldoutsUnsupported: held-out contexts get the normal value.
Target appsInfo: 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 IDsUnsupported: imported matching nobody.
Experiments and layersNot 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, percentagesWarnings: 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).

samples.jsonl
{"userID": "u1"}
{"userID": "u-829", "email": "dana@example.com", "country": "SA", "custom": {"plan": "pro"}}
{"key": "u-830", "country": "AE", "plan": "free"}
sh
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
  1. 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).
  2. Contexts that would get a different value are listed with both values. Differences decided by a percentage on both sides are counted separately.
  3. 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.