No results for ""
EXPAND ALL
  • Home
  • API docs

GIVE DOCS FEEDBACK

Rule-based segments

Read time: 8 minutes
Last edited: Jun 07, 2024

Overview

This topic explains how to build and manage rule-based segments. Rule-based segments let you target groups of contexts individually or by attributes.

Rule-based segments work well when you have a relatively small or well-defined group that you want to target. For example, you might create a rule-based segment when you want to target the following groups:

  • Everyone who uses your application and has an email ending in ".edu"
  • Employees in your company who have volunteered to participate in internal testing of new features
  • All contexts with a "tier" attribute of "enterprise"

You may notice that it's also possible to target each of these groups of contexts using targeting rules in a feature flag. However, it can simplify your configuration if you define the targeting rules in a segment, and then set up each flag to target the segment. If you create a segment, then you only have to define the targeting rules once. If your targeting rules ever change, you only have to change them in the segment. All of your feature flags that target the segment will automatically pick up the changes.

For some additional examples of working with rule-based segments, read Using entitlements to manage customer experience.

Create rule-based segments

When you create a rule-based segment, you can include and exclude individual targets and include targets that match specific rules.

To create a new rule-based segment:

  1. Navigate to the Segments list.
  2. Click Create segment. The "Create a segment" dialog appears.
The "Select a segment kind" step of the "Create a new segment" dialog
The "Select a segment kind" step of the "Create a new segment" dialog
  1. In the "Select a segment kind" step, choose Rule-based segments. The "Enter segment details" step appears.
  2. Give your segment a human-readable Name.
  3. Enter a Key for your segment. This field auto-populates based on the segment name, but you can change it if you like.
  4. (Optional) Add a Description.
  5. (Optional) Select or create Tags. Tags help you identify segments used by different teams or for different purposes within your organization.
  6. Click Save segment. The segment's Targeting tab appears.

To add or change the individual targets for your segment, read Target individual contexts.

To add or change the targeting rules for your segment, read Target contexts with rules.

Target individual contexts

You can individually target contexts for inclusion in or exclusion from a segment. You can also edit individually targeted contexts in bulk, and schedule the removal of individually targeted contexts from a segment.

To individually target a context:

  1. Navigate to the Segments list and choose the segment you wish to modify.
  2. Navigate to the Targeting tab.
  3. Click the "**+ Add rules" button and select "Include individuals" or "Exclude individuals."
  4. Choose the context kind for the contexts you want to target.
  • By default, the context kind is "user."

  • To update this, click Edit context. In the "Select context kinds" dialog, choose one or more context kinds and click Save.

    The "Select context kinds" dialog with two context kinds selected.
    The "Select context kinds" dialog with two context kinds selected.
  1. The "Included targets" or "Excluded targets" section updates to display the context kinds you selected.
  2. Choose contexts to include in or exclude from the segment.
  • You can search for contexts by name or key. Then, click the context name or key.
  • If you want to target a context that has not yet been encountered by LaunchDarkly, you can enter its key.
  • You cannot both include and exclude the same context.
  1. Click Save changes. The contexts are now individually targeted within the segment.

Here is an image of an individually targeted context:

An individually targeted context included in a segment.
An individually targeted context included in a segment.

To remove all included or excluded contexts from a segment, click Edit in the header of the "Included targets" or "Excluded targets" section. Then, click the overflow menu and select "Clear."

The overflow menu with "Clear" called out.
The overflow menu with "Clear" called out.

Bulk edit individual contexts

If you have a long list of contexts you want to add, remove, or replace within a segment, you can bulk edit contexts from a segment's Targeting tab. You can only perform bulk editing tasks for one context kind at a time.

To edit individual targets in bulk:

  1. Navigate to the Segments list and choose the segment you wish to modify.
  2. Navigate to the Targeting tab.
  3. In the "Included targets" or "Excluded targets" section, click Edit in the header of the section. Then, click the overflow menu.
  4. Select Bulk edit. The "Bulk edit targets for this segment" dialog appears.
  5. Use the action menu to select one of the following actions for the selected context kind:
  • "Add" adds the selected contexts as targets
  • "Remove" removes the selected contexts as targets
  • "Replace" replaces all currently targeted contexts with the selected contexts
  1. Use the context kind menu to select the context kind of the contexts you are targeting.
  2. Enter a list of context keys or email addresses in the Paste target keys field, separated by a comma or new line. LaunchDarkly looks up contexts by key or email and displays them in the list on the right. If you want to target a context that has not yet been encountered by LaunchDarkly, you must enter its key.
The "Bulk edit targets for this segment" dialog.
The "Bulk edit targets for this segment" dialog.

You can update the list on the right before you perform the selected action. The options for updating the list include the following:

  • All represents all of the contexts that may be impacted by the action, whether they are added or removed. Check the context's checkbox for the action to apply.
  • The checkmark represents inputted context keys that currently match contexts in the system. For example, if you enter the context key context-key-123abc, and context-key-123abc already exists in LaunchDarkly, it will show up in this list.
  • The question mark represents contexts with no matching records in LaunchDarkly. If you are adding contexts and the contexts do not currently exist in LaunchDarkly, they will be added to the targeting list.
  • The exclamation mark represents context key inputs with multiple matching records. For example, if you enter the email address sandy@example.com, but there are multiple context keys that have sandy@example.com as an email address, the system may return multiple matching records. You can select the correct record by clicking the checkbox.
  • Current lists all of the currently targeted contexts for the segment.
  1. Click Add targets, Remove targets, or Replace targets to perform the selected action.

Schedule context removal from segments

Scheduling removal dates is an Enterprise feature

Scheduling removal dates is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

You can schedule an expiration date and time on which LaunchDarkly removes a context from a segment. You can do this for existing contexts, or when you add a context to a segment.

This is useful if you want to give contexts temporary access to a feature that has their segment targeted. The ability to remove contexts from segments, instead of flag targeting, allows you to keep your flag's targeting rules permanent and clean.

To set a targeting removal date:

  1. Navigate to the Segments list and choose the segment you wish to modify.
  2. In the "Included targets" or "Excluded targets" section, click the calendar icon on the context you want to remove:
A context with the calendar icon called out.
A context with the calendar icon called out.
  1. In the "Schedule removal" dialog, set a date and time for the context to be removed from the segment.
  2. Click Save.

Additionally, when you add a context to a segment, you can schedule it for removal later by clicking Add and schedule removal.

Here is an image of the targeting field:

The targeting field with the "Add and schedule removal" option called out.
The targeting field with the "Add and schedule removal" option called out.

You can also use the REST API: Update expiring targets for segment

Target contexts with rules

You can use custom targeting rules in a segment to include targets that match specific rules. Segment targeting rules function the same way as flag targeting rules. To learn more, read Target with flags.

To customize a segment's targeting rules:

  1. Navigate to the Targeting tab of the segment you wish to modify.
  2. Click + Add rules at the top of the tab, or + between existing rules. Then choose which kind of rule to add:
  • Select "Target segments** to create a targeting rule based on an existing segment.
    • In the Operator menu, select whether you want contexts in these segments or not in these segments to match the targeting rule.
    • In the Segments menu, enter or select the segments you want to target.
  • Select "Build a custom rule" to create a targeting rule based on contexts and their attributes.
    • Specify a Context kind, Attribute, Operator, and Values for the rule.
  1. (Optional) Enter a name for the rule.
  2. If you want to add more criteria, click the + beside the rule criteria.
A rule on a segment.
A rule on a segment.
  1. Select whether to include in the segment all contexts that match the rule, or a percentage of contexts that match the rule.
  • If you select a percentage of contexts, select a context kind and enter the percentage to include in the segment.
  1. Click Save.

To reference this rule when working with other members of your organization, click the link icon to copy a link to this rule.

To remove a targeting rule from a segment, click Edit*. The click the overflow menu and select "Delete rule."

Understanding segment rule logic

When you specify rules for a segment, LaunchDarkly parses them in order of appearance from top to bottom. You can change how segment targeting applies based on the order of the rules you create.

Target a segment in multiple flags

You can target the same segment from multiple feature flags. If you have many flags that need the same targeting rules, it may be easier to set up a single segment with those rules for your flags to target, rather than setting up the rules repeatedly in each flag.

If you target only a percentage of contexts that match your segment targeting rule, each flag that targets that segment will include the same contexts in its targeting, assuming there are no other differences between the flags' targeting rules.

For example, imagine you configure a segment to target 50% of user contexts that match its rule. As a result, the segment includes user contexts Adrian, Bailey, and Cristiano, and excludes user contexts DJ, Ellis, and Felicia. If there are no other differences between the flags' targeting rules, each flag that targets that segment will also include user contexts Adrian, Bailey, and Cristiano in its targeting, while excluding user contexts DJ, Ellis, and Felicia.