> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/your-data/labels/smart-labels.md). # Smart Labels A **label** is a tag you put on a person. Apply and remove it by hand, or give the label **rules** and let Flapjax maintain it for you. A label carrying rules is a **smart label**, also called a dynamic or rule-based label. Flapjax watches your data and adds or removes the label as people start and stop matching your rules. This page covers how smart labels work and how to configure them. For a shorter, more conceptual walkthrough, see [How labels are applied in real time](/docs/your-data/labels/how-labels-are-applied-in-real-time.md). *** ## Manual and dynamic labels Every label is one of two kinds at any moment. One thing decides which: whether the label carries rule groups. * **Manual** labels carry no rule groups. The label stays on a person until you remove it, or an automation action does. You control it directly. * **Dynamic**, or smart, labels carry one or more rule groups. Flapjax evaluates those rules and keeps membership in line with them, assigning and removing on its own. A label switches from manual to smart on its [**detail page**](/docs/your-data/labels/label-detail-page.md). Open the label, change its assignment mode from **Manual** to **Rule-based**, and add at least one rule group. Switching back to **Manual** clears the rules and returns the label to hand-applied. *** ## Rule groups A smart label runs on one or more **rule groups**. Each group is an independent way for the label to match, so a person matching *any* group gets that group's outcome. Every group has three parts: a **trigger** for when to check, a **filter** for what to require, and an **effect** to add or remove. ### Trigger: when the group is checked Each group fires one of two ways, and exactly one applies per group. * **When an event happens**, meaning event-driven. Flapjax re-checks the group the moment a matching change arrives. The event can be: * a **person is updated**, * a **record is added** to a stack, or * a **record is updated** on a stack. Narrow an event trigger further to fire only **when a specific attribute changes**, say only when a person's `lifetime_value` moved. * **On a recurring schedule**, meaning time-driven. Flapjax runs the group on a clock rather than in reaction to a change. That suits rules about the *passage of time* rather than a specific event. Frequencies run **hourly, daily, weekly or monthly**, each with its time, weekday or day-of-month and timezone. Scheduled groups filter on **person attributes** alone, since no triggering event exists to draw record fields from. ### Filter: what the group requires Inside the trigger you build a **filter**: conditions of field, operator and value, joined with **AND** and **OR**, in the same rule builder segments and automations use. See Rules & segment builder for how conditions get built, and [Data types](/docs/core-concepts/data-types.md) for the operators each field type offers. An empty filter means "every person this trigger applies to". The group then matches on the trigger alone. Add a **segment guard** too if you like. Pick a people segment and the group applies only to people already in it. Delete that segment later and the label auto-pauses, covered in [Lifecycle](#lifecycle). ### Effect: add or remove Each group either **adds** the label to matching people or **removes** it from them. The effect defaults to add. Combine an add group and a remove group on one label and it stays accurate on both sides. People flow in as they qualify and out as they stop. ### Remove wins Flapjax looks at every group that applies to a change and resolves them with one priority rule. **Any applicable group saying *****remove***** takes the label off.** Otherwise a group saying *add* puts it on, if the person lacks it. Remove-wins keeps labels conservative. Nobody keeps a label they no longer qualify for. *** ## Real-time evaluation Smart labels skip the nightly batch. Event-driven groups react the instant a matching change is processed, and scheduled groups fire on their clock. The mechanics live in the event pipeline. Two points are worth knowing: * **Fresh snapshot.** Before deciding, the evaluator re-reads the person's *current* labels from the database rather than trusting the label list attached to the incoming event, which may be stale. That avoids double-adds and phantom removes under concurrency. * **Loop-safe.** Each label rides Flapjax's loop-detection machinery under a synthetic automation identity, `1,000,000,000 + labelID`. A label whose own change would re-trigger itself endlessly gets caught and paused rather than looping. For the full evaluation order, see the client guide [How labels are applied in real time](/docs/your-data/labels/how-labels-are-applied-in-real-time.md). *** ## Lifecycle * **Auto-save.** Your edits save a moment after you stop typing, so the rules carry no Save button. A "syncing" indicator appears during a save. Add rules to a label for the first time and Flapjax saves them **inactive**, so nothing runs until you turn the label on. * **The active switch locks the config.** Every smart label has an **active** toggle. An active label runs its rules and **locks** the configuration, so it cannot change mid-evaluation. A banner reminds you to switch it off to edit. Turn it off, change the rules, turn it back on. An inactive label keeps its configuration, and the evaluator skips it. * **Auto-pause on a broken dependency or a loop.** A smart label depends on what its rules reference. Delete a **segment guard**, or write rules that would **loop endlessly**, and Flapjax **pauses** the label to protect your data. A banner explains why, with a reason such as `segment_no_longer_available` or `infinite_loop_detected`. A paused label stops changing on its own and keeps the assignments it made. This pauses the *label* alone, which differs from an automation being paused. * **Resume.** Fix the underlying problem, then click **Resume** on the banner to switch the label back on. *** ## Worked examples The fields below, `lifetime_value` and `last_active_at`, are illustrative custom attributes. Swap in whatever attributes your own people carry. ### Example 1: event-triggered "High Value", add and remove Two groups on one label keep **High Value** in step with a spending threshold. | Group | Trigger | Filter | Effect | | ----- | ------------------------ | -------------------------------------------------- | ----------------------- | | 1 | When a person is updated | `lifetime_value` **is greater-or-equal to** `1000` | **Add** *High Value* | | 2 | When a person is updated | `lifetime_value` **is less than** `1000` | **Remove** *High Value* | A customer whose `lifetime_value` crosses 1000 gets the label from group 1. A drop back below 1000 takes it off through group 2. Remove wins, so a single update matching both sides still removes the label. ### Example 2: recurring "Dormant", time-based Some labels are about *inactivity*, which no single event announces. Run them on a schedule. | Group | Trigger | Filter | Effect | | ----- | -------------------------- | ----------------------------------------------- | -------------------- | | 1 | Daily (recurring schedule) | `last_active_at` **is before** 30 days ago | **Add** *Dormant* | | 2 | Daily (recurring schedule) | `last_active_at` **is on-or-after** 30 days ago | **Remove** *Dormant* | Flapjax checks everyone each day. People quiet for 30 days pick up **Dormant** from group 1. Anyone active again loses it on the next run through group 2. Keep only group 1 if you would rather remove the label another way. Pairing add with remove keeps membership self-correcting. *** ## Where smart labels show up A smart label's [detail page](/docs/your-data/labels/label-detail-page.md) charts its membership over time and links straight to the people holding it. Labels feed **segments** and **reports** too, so one well-designed smart label keeps your whole workspace grouped correctly with no manual upkeep. See also [Managing labels](/docs/your-data/labels/managing-labels.md) and [Browsing labels](/docs/your-data/labels/browsing-labels.md).