Skip to Content
harness-fme

🚩 Flags, definitions and segments

Reading and changing flags, per-environment definitions, classic and rule-based segments, flag overviews and web UI links.

A flag exists once per workspace. Its targeting lives in a definition, one per environment. All the functions below take the client first and return an FmeResult.

Flags

import {
  listAllFeatureFlags,
  getFeatureFlag,
  createFeatureFlag,
  updateFeatureFlag,
} from "@kud/harness-fme"

const flag = await getFeatureFlag(client, {
  workspaceId,
  flagName: "checkout_new_flow",
})
FunctionDoes
listFeatureFlags / listAllFeatureFlagsOne page or every flag, filtered by tag, rolloutStatusId, name
getFeatureFlagOne flag
createFeatureFlagNeeds workspaceId, trafficType, name, optional description
updateFeatureFlagPatches description, tags, owners, rolloutStatusId; fails if you give none
archiveFeatureFlag / unarchiveFeatureFlagArchive or bring back
deleteFeatureFlagResolves to { deleted: flagName }

Reads flatten the traffic type, so trafficTypeId is always available next to the nested trafficType. updateFeatureFlag accepts tags as plain strings or { name } objects.

Definitions

A definition holds the treatments, default rule, targeting rules and the killed state for one flag in one environment.

FunctionDoes
getFlagDefinitionRead one definition (404 when none exists)
listFlagDefinitions / listAllFlagDefinitionsOne page or all definitions in an environment
createFlagDefinition / updateFlagDefinitionPOST or PUT a full definition
deleteFlagDefinitionRemove the definition from one environment
killFeatureFlag / restoreFeatureFlagKill (serve the default treatment) or restore
addSegmentToTreatmentRead, add a segment to a named treatment, write

The create and update calls take the definition as a JSON string and optional title and comment. Workspaces with requiresTitleAndComments reject writes without them, so supply both there. They fail with a clear message when the JSON is invalid, or when title and comment are given for a definition that is not an object.

addSegmentToTreatment exists so you never have to replace a whole definition just to add a segment, where a dropped field would silently wipe targeting. It is idempotent: if the segment is already on the treatment it returns { unchanged: true } without writing.

For changing many flags, prefer the safe-write engine.

Reading a definition

Pure helpers in definition.ts interpret a definition without any request:

import { classifyRollout, describeDefaultRule, isFullyServing } from "@kud/harness-fme"

classifyRollout(def) // "killed" | "on" | "off" | "partial" | "unknown"
describeDefaultRule(def) // "on 50% / off 50%"
isFullyServing(def, "on") // true when the default rule serves "on" at 100%

classifyRollout lets a killed flag win over everything else, since a killed flag serves its default treatment whatever its rules say. Treatment names default to on and off; pass { on, off } for others.

Flag overviews

findFlags(client, workspaceId, { tag, prefix, includeInactive }) lists flags by tag and name prefix, leaving out archived ones unless asked. buildFlagRows then produces one row per flag with a view per environment, choosing per flag between single reads and listing the whole environment, whichever costs fewer requests:

const flags = await findFlags(client, ws.id, { prefix: "checkout_" })
const rows = await buildFlagRows(client, {
  workspaceId: ws.id,
  flags: flags.ok ? flags.data : [],
  environments,
})

Each environment view carries state (including "undefined" for a flag with no definition there) and a readable defaultRule.

Segments

Classic segments hold lists of keys.

FunctionDoes
listSegments, listSegmentDefinitionsWorkspace segments, and their state per environment
createSegment, deleteSegmentLifecycle in a workspace
enableSegmentInEnvironment, disableSegmentInEnvironmentSwitch a segment on or off in one environment
listSegmentKeysMember keys, to check whether a person is already in
addSegmentKeys, removeSegmentKeysChange membership
await addSegmentKeys(client, {
  environmentId,
  segmentName: "beta_testers",
  keys: ["user-1042", "user-2210"],
  title: "Add testers",
  comment: "Two more testers for the beta.",
})

addSegmentKeys refuses an empty list and more than MAX_SEGMENT_KEYS_PER_CALL (10,000) keys, with a message asking you to split the call. Pass replace: true to replace the membership instead of adding to it.

Rule-based segments

Rule-based segments are defined by rules rather than key lists, and have their own set: listRuleBasedSegments, getRuleBasedSegment, createRuleBasedSegment, deleteRuleBasedSegment, listRuleBasedSegmentDefinitions, updateRuleBasedSegmentDefinition (JSON string), enableRuleBasedSegmentDefinition, disableRuleBasedSegmentDefinition and createRuleBasedSegmentChangeRequest for workspaces that require approval.

buildFlagUrl(client, { accountId, orgGuid, workspace, flag, environment }) assembles the deep link to a flag's definition page. Workspace, flag and environment can be names or ids. The account id and organisation GUID are platform identifiers the admin API does not expose, so you supply them.