---
title: "Value Mapping"
description: "Map raw device values to numeric outputs using ordered match rules"
source_url: https://ai-ops.com/docs/tags/value-mapping
---

# Value Mapping

Value mapping converts raw device values into numeric outputs using an ordered list of match rules. When enabled on a tag, every value read from the device is evaluated against the rules — the first matching rule determines the output.

Common use cases include:

- Converting status strings like `"Off"` and `"On"` to numeric values `0` and `1`
- Mapping numeric ranges (e.g. values above 100 map to an alarm state)
- Normalizing wildcard-patterned strings (e.g. anything ending in `_active` maps to `1`)
- Providing a catch-all default when no specific rule matches

## How It Works

Value mapping rules are evaluated **top-to-bottom**. The first rule that matches the incoming value wins — its output becomes the tag's numeric value, and the original raw value is preserved as the **lookup key**.

For example, given these rules:

| # | Match Type | Pattern | Output |
|---|------------|---------|--------|
| 1 | Exact | Off | 0 |
| 2 | Exact | On | 1 |
| 3 | Any | — | -1 |

If the device returns `"On"`, rule 2 matches. The tag's value becomes `1` and the lookup key shows `"On"`. If the device returns something unexpected like `"Standby"`, rules 1 and 2 don't match, but rule 3 (the catch-all) does — the value becomes `-1`.

> [!TIP] Order matters
> Rules are checked in the order you define them. Place specific rules at the top and catch-all rules at the bottom. You can reorder rules using the arrow buttons in the editor.

## Enabling Value Mapping

Value mapping is configured in the **Advanced** section of a tag's configuration:

1. Open the tag's **Configuration** tab
2. Scroll to the **Advanced** section
3. Toggle **Use Value Mapping** on
4. Add your rules using the rule editor
5. Save your changes

You can also enable value mapping when creating a new tag — the same settings are available in the create form's advanced section.

## Match Types

The rule editor supports eight match types:

| Match Type | Description | Pattern Format | Example |
|------------|-------------|----------------|---------|
| **Exact Match** | Value equals the pattern exactly | Text or number | `Off`, `42`, `3.14` |
| **Greater Than** | Numeric value is strictly greater than the pattern | Number | `100` |
| **Greater or Equal** | Numeric value is greater than or equal to the pattern | Number | `100` |
| **Less Than** | Numeric value is strictly less than the pattern | Number | `0` |
| **Less or Equal** | Numeric value is less than or equal to the pattern | Number | `0` |
| **Between** | Numeric value is between min and max (inclusive) | Two numbers | `10` and `50` |
| **Wildcard Pattern** | Glob-style pattern matching | Pattern with `*` or `?` | `*_active` |
| **Any (Catch-all)** | Always matches, regardless of value | No pattern needed | — |

### Exact Match

Matches when the raw value equals the pattern. For numeric values, this uses a tolerance-based comparison to handle floating-point imprecision — so a value of `0.30000000000000004` (the result of `0.1 + 0.2`) will correctly match a pattern of `0.3`. For string values, it performs a direct string comparison.

### Numeric Comparisons

The **Greater Than**, **Greater or Equal**, **Less Than**, **Less or Equal**, and **Between** match types work with numeric values only. If the raw value cannot be parsed as a number, these rules are skipped and evaluation continues to the next rule.

**Between** matches when the value falls within a range (inclusive on both ends). In the editor, you enter the minimum and maximum values separately.

### Wildcard Pattern

Uses glob-style matching where:

- `*` matches any number of characters
- `?` matches exactly one character

For example, the pattern `Sensor_*_OK` would match `Sensor_01_OK`, `Sensor_Temp_OK`, etc.

### Any (Catch-all)

Always matches. Place this as the last rule to provide a default output when no other rule matches. No pattern is needed.

> [!WARNING] Unmatched values cause errors
> If value mapping is enabled but no rule matches the incoming value, the tag will enter an error state. Always include a catch-all rule at the bottom if you want to handle unexpected values gracefully.

## Additional Options

### Case-Insensitive Matching

When enabled, **Exact Match** and **Wildcard Pattern** rules ignore letter case. For example, `"off"`, `"OFF"`, and `"Off"` would all match a pattern of `"Off"`.

This setting has no effect on numeric comparisons (Greater Than, Less Than, Between, etc.) since numbers don't have case.

### Reverse Mapping on Write

For **output** tags, enabling reverse mapping converts the numeric output value back to the original string before writing to the device. This only works with **Exact Match** rules — it finds the first exact rule whose output matches the value being written and sends the rule's pattern string to the device instead.

For example, if an AI model writes the value `1` to an output tag with the rules above, reverse mapping would convert it back to `"On"` before sending it to the device.

> [!NOTE] Output tags only
> Reverse mapping is only relevant for output tags that write values back to a device. It has no effect on input tags.

## Viewing the Lookup Key

When value mapping is active, the tag's live data displays both:

- **Value** — the numeric output from the matched rule
- **Lookup Key** — the original raw value from the device, shown in brackets next to the value

This appears in the tag list table and on the tag's overview page. It helps you verify which raw value was received and which rule matched.

## Examples

### String-to-Number Mapping

Map device status strings to numeric values:

| # | Match Type | Pattern | Output |
|---|------------|---------|--------|
| 1 | Exact | Off | 0 |
| 2 | Exact | On | 1 |
| 3 | Exact | Standby | 2 |
| 4 | Exact | Error | 3 |
| 5 | Any | — | -1 |

### Numeric Range Mapping

Classify a temperature reading into zones:

| # | Match Type | Pattern | Output |
|---|------------|---------|--------|
| 1 | Less Than | 0 | 0 |
| 2 | Between | 0 and 25 | 1 |
| 3 | Between | 25 and 35 | 2 |
| 4 | Greater Than | 35 | 3 |

### Wildcard Pattern Matching

Map device response codes that follow a naming pattern:

| # | Match Type | Pattern | Output |
|---|------------|---------|--------|
| 1 | Wildcard | *_OK | 1 |
| 2 | Wildcard | *_WARN | 2 |
| 3 | Wildcard | *_FAIL | 3 |
| 4 | Any | — | 0 |