> For the complete documentation index, see [llms.txt](https://docs.tricloudnexus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tricloudnexus.io/management-portal/oee/equipment/tag-mapping.md). # Tag Mapping Wire each OEE pillar to the live tag values that drive it. Three input groups, three input modes per slot. The **Tag Mapping** tab on an Equipment tells the OEE engine which **tag** carries which signal. Every input slot accepts the same three input modes, so once you’ve learned the pattern on one slot it works the same way everywhere else.

Tag Mapping tab — three input groups, each with a "Configure" trigger that opens the Select Tag Mapping dialog

*** ## The three input groups | Group | Purpose | Pillar driven | Reference | | ----------------------- | ------------------------------------------------ | ------------- | -------------------------------------------------------------------------------------------- | | **State & Error Codes** | Equipment Run State + optional Error Code(s) | Availability | [State & Error Codes](/management-portal/oee/equipment/tag-mapping/state-and-error-codes.md) | | **Product & Order** | Current Product Id + Order Id + Ordered Products | Performance | [Product & Order](/management-portal/oee/equipment/tag-mapping/product-and-order.md) | | **Data Quality** | Two of three counts: Total, Approved, Rejected | Quality | [Data Quality](/management-portal/oee/equipment/tag-mapping/data-quality.md) | Each group is independent — you can wire only the tags the pillars you’ve enabled actually need. A field that’s required by validation has a red asterisk and shows a tooltip identifying it; optional fields can stay empty. *** ## The Select Tag Mapping dialog Click the **Configure** button to open the tag dialog:

Select Tag Mapping — the asset hierarchy on the left, available tags on the right, and a Value Parser pane that adapts to the selected tag’s data type

The dialog has two top-level tabs: * **Single Tag** — pick a single tag from one of the available [Asset Hierarchies](/management-portal/designer/assets/asset-hierarchies.md), then choose how the value should be interpreted (Direct or, for string tags, JSONata). * **Calculation** — combine multiple tags into one signal using a variable-based expression. See [Calculations](/management-portal/oee/equipment/tag-mapping/calculations.md). The currently active tab determines the **mapping type** stored on the slot: | Tab | Mapping type | Stored expression / variables | | ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Single Tag (Direct) | `Direct` | None — the source tag’s value is used as-is. | | Single Tag (Accumulating) | `Accumulating` | Roll-over value (e.g. `65536` for a 16-bit counter) — the engine reports the *delta* between successive readings, handling roll-over automatically. | | Single Tag (Jsonata) | `JsonataExpression` | A JSONata `value` expression plus optional `start`/`end` timestamp expressions. | | Calculation | `SymbolicExpression` | A list of `(symbol → tag)` variables and an arithmetic expression like `a+b/c`. | *** ## Single Tag — Direct vs. Accumulating After you select a tag in the Single Tag tab, a **Value Parser** pane appears below the grid. For numeric (analog/digital) tags it offers two options: | Option | When to pick it | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Direct** | The tag already emits the signal you want — a state code, an instantaneous count, a percentage. The engine uses every reading as-is. | | **Accumulating** | The tag is a free-running counter (cycle count, units produced) that resets at a known **Roll Over Value** (e.g. `65536`). The engine reports the *delta* between successive readings, handling roll-overs automatically. | Pick Accumulating when the value the tag emits is monotonic-with-roll-over and you actually want the change between readings — typical for produced-unit counters off a PLC.

Select Tag Mapping — Single Tag with Accumulating value parser selected; the Roll Over Value field configures the counter's maximum before it wraps

The delta is calculated as: * `delta = current − previous` when `current ≥ previous` (normal increment). * `delta = (RollOverValue − previous) + current` when `current < previous` and a Roll Over Value is configured (counter wrapped past its max). * `delta = current` when `current < previous` and no Roll Over Value is configured (treated as a counter reset). Set the Roll Over Value to match the counter’s width (e.g. `65536` for a 16-bit counter, `4294967296` for a 32-bit counter) so wraps are credited correctly. Leave it empty for counters that you know reset to 0 explicitly (e.g. at start of shift) — the engine then treats every backward jump as a reset. *** ## Single Tag — JSONata for string tags If the selected tag has a String measurement type — typical when an MQTT or OPC tag carries a JSON payload — the Value Parser switches to a JSONata editor: | Option | When to pick it | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Direct** | The tag value is exactly the string you want (e.g. `Running` already). | | **Jsonata** | The tag carries a structured payload and you want to extract a field from it. Write a [JSONata](https://jsonata.org/) expression that resolves to the value to use. | For interval-mode error codes and order tags (see [State & Error Codes](/management-portal/oee/equipment/tag-mapping/state-and-error-codes.md) and [Product & Order](/management-portal/oee/equipment/tag-mapping/product-and-order.md)), the JSONata pane also exposes optional `Start Timestamp` and `End Timestamp` expressions so you can pull the interval bounds out of the same payload. The **Open Query Editor** button opens the JSONata Query Window with the source tag’s example payload pre-populated (for MQTT topics that have one configured) so you can iterate on the expression with example preview before saving.

JSONata Query Window — example payload on the left, expression on the right, output below; "Valid Payload" indicates the expression resolved successfully

*** ## Calculation — variables + expression When no single tag carries the signal you need, switch to the **Calculation** tab in the Select Tag Mapping dialog. You define one or more named variables (`a`, `b`, `c`, …) each pointing at a tag, then write an arithmetic / boolean expression that evaluates to the signal value. The same engine drives the [Equation data connector](/management-portal/designer/assets/data-connectors/equation.md) — the [Operators](/management-portal/designer/assets/tags/collect/configuration/equation/operators.md) and [Functions](/management-portal/designer/assets/tags/collect/configuration/equation/functions.md) reference pages list everything you can use. See [Calculations](/management-portal/oee/equipment/tag-mapping/calculations.md) for the full procedure including Validate and Evaluate. *** ## Tooltips for every field Every input on the Tag Mapping tab has a tooltip, that describes the purpose a use. Click it to view a detailed description. *** ## What each pillar needs (summary) | Pillar | Required tags | Optional tags | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | **Availability** | Equipment Run State | Error Code (and Error Code Closed in Event Pair mode) | | **Performance** | Current Product Id, Ordered Products, order-completion event (see below) | — | | **Quality** | Two of: Products Total, Products Approved, Products Rejected (the third is derived), plus order-completion event (see below) | — | Performance and Quality both require an **order-completion event** because their count tags are aligned to orders by exact timestamp match. Configure **Order Id** in **Single Event (start & end)** mode (with an end-timestamp expression) or **Order Start + Order End** in **Event Pair** mode. See [Aligning counts with order completion](/management-portal/oee/equipment/tag-mapping/product-and-order.md#aligning-counts-with-order-completion). If a pillar is disabled on the [Equipment tab](/management-portal/oee/equipment/settings-and-targets.md), its tag fields are not required even if they’re shown.