Create a Data Rule

The rule builder walks you through three steps: When the rule should fire, Then what happens, and a Preview of what it would flag. This guide covers that flow end to end, from opening Data Rules through to saving, then editing a rule afterwards.

Before you start

You need:

Write access to the project’s Data Rules. Ask an admin if the Add data rule button is greyed out.
A clear sense of the measurement or calculation you want to validate, and the threshold or pattern that defines a problem.

Step-by-step

Open Data Rules

Navigate to Project Settings → Data Rules. The page lists every rule configured for the project, with what it runs on, its status, and the dates it applies to.Click Add data rule to start.

Choose what the rule checks

The New data rule screen offers two kinds of rule:

Kind	When to use
Data Points	Runs on each data point as it is ingested or updated. Best for catching problems in raw measurements, such as out-of-range values or missing values.
Batch Calculation	Runs against model calculation results when a batch is created or updated. Best for catching downstream calculation issues, such as a CI score drifting outside expected bounds.

Picking one starts the wizard. You can come back to this choice from the Change link on the When step at any point before saving. Re-picking the same kind keeps your work; switching to the other one clears the condition, because the two author against different variables.

When: what the rule looks for

This step holds five things, in order:

The Trigger type you picked, shown as a chip. For a Batch Calculation rule, also select the model whose results the rule reads.
The Condition. Type {{ to open autocomplete and pick a data point or model node. When the condition evaluates to true on a record, that record is flagged.
{{data-point.carbon_content}} not between 0.50 and 0.90
See Rule Expressions for the full language reference.
The Rule name, shown in the rules list and in audit history. Keep it brief and stable, even if you later edit the condition.
The Effective period. Choose Always active, or Fixed range to set an Effective from and Effective to. Saving evaluates every matching record inside the period, both historical and going forward, unless the rule runs on demand (below). Records outside it are not touched.
Run only on demand. Off by default. Turn it on for a rule that should run only when you evaluate a period, rather than on every data point as it arrives. See Rules that run on demand.

Next stays disabled until the step has what it needs. Hover it to see which fields are missing.

Data Points rules apply across the whole project. Autocomplete offers every data point type that is captured on an event, and the data points that get flagged come from the condition itself. A calculated data point type, one a model computes, is not offered, and a condition naming one is rejected when you save. Test a computed value with a Batch Calculation rule.One rule reads a single event type. Autocomplete does not enforce that, so a condition can be written across two event types and is rejected when you save, naming the event types it spans.

Then: what happens

Pick the Action:

Action	What it does
Alert	Flag only. No value change.
Substitute	Replace the value with the first method that produces one.

Substitute appears only on Data Points rules. See Substituting a value for what a correction does to the data.

Acting on the whole window

When the condition contains a windowed aggregate, a dropdown appears under the action: What to flag on an alert rule, What to correct on a substitute rule. It decides which data points the rule acts on when the condition is true:

Option	Acts on
Only the matching data point	The most recent data point in the window, the one that made the condition true. This is the default.
Everything in the window	Every data point of this type in the window.
Repeats in the window	Data points in the window that repeat the value before them. The first one keeps its value.
The whole run	Every data point with the same value in a row, even outside the window. Data points another rule already corrected stay with that rule.

The whole run is offered only when the condition tests MIN = MAX on every data point the rule flags: a stuck-sensor condition. On that condition the fill and trailing methods leave the run of repeated values out when they look for a replacement, so the replacement is never the stuck value itself. See Catching a stuck sensor for the condition and for when to pick Repeats in the window or The whole run.Where the condition uses two windows, the rule acts only on the data points inside both.

If the action is Substitute

Name the value the rule corrects under When this rule fires, substitute. This is a single choice and it is required. The list offers the number data points your condition references, and picks for you when there is only one to pick, so a condition reading one number and one text value fills it in for you too.Then build the chain under Substitution methods. Methods are tried in order until one produces a value. Click Add substitution method to append one, click a row to configure it, and use Move up, Move down, and Remove step to arrange them.

Method	What it uses	What you set
Constant	A fixed value you set.	Value
Forward fill	The most recent earlier value that passes this rule.	nothing
Backward fill	The nearest later value that passes this rule.	nothing
Cross fill	Another data point type’s value for the same period, from the same event, or at the same asset when it is captured on another event type.	Data point to use
Trailing average	The average of the valid values in the window.	Window
Trailing min	The lowest valid value in the window.	Window
Trailing max	The highest valid value in the window.	Window
Percentile	The chosen percentile of the valid values in the window, such as the 90th. Needs at least two values to draw on.	Percentile, Window

For example, take the rule {{data-point.biogas_flow}} < 300 on an hourly meter. The meter came online at 00:00 and read 402, 398, 405, 411, 407 and 409 up to 05:00, then 42 at 06:00, so the rule fires on 06:00. The next data point, at 07:00, is 412, and a backup meter on the same event read 401 at 06:00. Each method on its own would write:

Method	Writes	Why
Forward fill	409	The 05:00 value.
Backward fill	412	The 07:00 value.
Cross fill, from the backup meter	401	The backup meter’s value at 06:00.
Trailing average, 6 hours	405.33333	The six values from 00:00 to 05:00 add up to 2432; divided by 6. Averages are rounded to 5 decimal places.
Trailing min, 6 hours	398	The 01:00 value.
Trailing max, 6 hours	411	The 03:00 value.
Percentile, 90th, 6 hours	410	Halfway between 409 and 411, the two values either side of the 90th percentile.
Constant, 400	400	The value you set.

In a chain of Cross fill, Trailing average and Constant, the rule writes 401. A method’s value is refused if the rule would fire on it, so if the backup meter had also read below 300, the chain would move on and write 405.33333. The constant would never be reached.Every method except Constant also has a Data point to use. It starts on the data point being corrected; pick another Number data point type to draw the replacement from that one instead. Values are copied with no conversion, so the source has to be in the same unit as the value being corrected, unless it is a Cross fill reading from the same event. A source captured on another event type is read at the same asset.The Window control offers two kinds. Trailing is a span reaching back from the value being corrected: set how many, and a unit from seconds to years. Calendar is the value’s own period: set the unit, days to years, how many consecutive periods it covers, and how many periods back it starts. A calendar window one period back is the previous complete month, quarter or year, which is how you say “last month’s average” rather than “this month so far”.A calendar window over the value’s own period also has a Covers setting. Month to date (or the matching unit) is the default and reads the period up to the value being corrected. Whole month reads the entire period, including data points after the one being corrected, so a gap is filled from the month’s full average. Whole month is available only on a single period with no periods back, and only on a rule that runs on demand.

With Data point to use left on the data point being corrected, the fill and trailing methods only draw on values carrying the same tracking ID as the one being corrected. On a project that sets a tracking ID per delivery or per ticket, that usually leaves nothing to draw on, so the rule raises an alert instead of correcting. If a substitute rule corrects nothing and you expected it to, check the tracking IDs on the events it reads. With another data point type picked, they read that type’s values at the same asset instead, whatever their tracking ID.

The last row of the chain is always Flag as alert: if no method produces a value, the value is left as it is and an alert is raised. Adding a Constant changes that row to say the alert will not fire, because a constant always produces a value. Anything you place after a constant is struck through and marked as never running.Forward fill, backward fill and Constant drop out of the picker once used, since repeating one can only fail where it failed the first time. The other methods stay selectable because their settings change what they read, so a second Trailing average over the same window is only caught when you save.Optionally fill in If no method produces a value, alert with to word that alert yourself. Left blank, it states that the correction could not be applied.

Holding corrections for approval

Below the chain, Require approval decides whether the rule writes its corrections or proposes them. With it off, a correction is written as soon as a method produces a value. With it on, each match becomes a proposal: the data point keeps its measured value until someone approves or rejects it, and a data point with a proposal waiting cannot go into a new batch. See Approve corrections for deciding them.Turn it on for a rule you are still learning to trust, or where each replacement value should be signed off. A rule that corrects many data points raises as many proposals. It is off on every new rule.

If the action is Alert

Decide which data point the alert attaches to, under When this rule fires, flag:

Option	Effect
Automatic	Any data point the condition references can be flagged. The eligible ones are listed underneath.
Specific data points	You pick which of the referenced data points can be flagged. Only those raise an alert; the rest are read as context.

Reach for Specific data points when a rule reads one value but is really about another. A rule like {{data-point.vent_1_speed}} > 90 OR {{data-point.vent_2_speed}} > 90 covers two pieces of equipment, so flagging both when only the first breached sends whoever triages the alert to the wrong place.You can only pick data points the condition already references. If you later edit the condition and drop one, it is removed from the selection too. Batch Calculation rules do not use this control.Write the Alert message, the explanation shown on each flagged record. It is generated from the condition by default; edit it to read naturally for the people triaging alerts.The rule name and condition sit above this step read-only. Edit expression takes you back to the When step to change the condition.

Preview: what it would flag

On a substitute rule this step reads What this rule would correct, or What this rule would propose with Require approval on, and it shows which records the condition matches. It does not compute the replacement values; save the rule and read what it produced.The preview stays empty until you click Validate. Validating checks that the condition parses and that every variable resolves, then runs the rule against the project’s recent data under the heading named above.A preview covers the last 90 days unless you give it a range of your own, and a wider range is honoured when you do.Read the result before saving:

Matches listed. Check they are the records you expected. Unexpected matches mean the condition is too broad.
Nothing matches yet. The rule is valid and will run on new data as it arrives, or, on a rule that runs on demand, when you evaluate a period. Nothing in the window matches it. A range filter appears with this result, so widen the window there, or adjust the condition, to see historical matches.
A sampling note. On projects with a lot of events the preview covers only the most recent ones. Save the rule to evaluate the full history.

A condition using WITHIN previews the same result it will produce once saved. Windowed conditions are heavier to work out, so the sampling note above appears on a smaller project than it would for a rule without one. See Rule Expressions for the detail.The preview applies the same validation as saving, so a condition the preview accepts is one the rule builder will save.

Save the rule

Click Save. For a rule that runs as data arrives, Mangrove confirms that saving will evaluate everything the rule matches, then evaluates every matching record inside the effective period. On a substitute rule the confirmation says the values it corrects will be overwritten, or, with Require approval on, that matches become proposals and nothing changes until someone approves.Editing a saved substitute rule applies the new methods going forward. Values it already corrected keep the value they have. To redo them with the new methods, revert the runs that wrote them, then evaluate the period again; see Editing a rule does not redo earlier corrections.You land on the rule’s page, showing its effective period, its counts, and the records found during evaluation; see The rule page. Unless Run only on demand is on, the rule is live: every new data point or batch generation inside the effective period runs the condition, and the rule alerts or substitutes as its action says.A rule with Run only on demand on evaluates nothing on save and does not run as data arrives. It runs over a period when you start one from its Runs tab with Evaluate a period.

Rules that run on demand

Run only on demand runs a rule over a period when you start it, rather than as data arrives. Use it for checks that read a whole period, such as a month’s capture rate or a gap filled from the whole month’s average, so the rule runs once the period is complete. An on-demand rule:

Is not evaluated when you save it, or when new data points arrive. A Batch Calculation rule that runs on demand is not evaluated when its model run finishes.
Runs over a period when you click Evaluate a period on its Runs tab, or start a run through the API with Re-evaluate a rule over a period.
Shows Runs on demand on the rule’s page.

Two substitute rule settings need it:

A Whole month (or whole quarter, whole year) window, because it reads data points after the one being corrected. A data point whose period has not ended when the run starts is left uncorrected, and its alert says to evaluate the rule again after the period closes. While a rule has a whole-period window, Run only on demand cannot be turned off. Change the window first.
A condition reading DATA_CAPTURE_RATE or TIME_NOT_CAPTURED of a data point other than the one being corrected. A substitute rule cannot read the capture rate of the data point it corrects. See Data capture rate.

How rules appear in the list

The Runs on column shows what each rule binds to: Data Points, or Batch Calculation with the model name. The play icon on a rule’s row opens Evaluate a period for that rule without opening it. While the rule is evaluating, the icon is replaced by a spinner.

The rule page

Open a rule from the Data Rules list to see its condition, what it runs on, its action, and its effective period. A substitute rule also shows its Substitution methods.

Counts

Cards above the tabs count the records evaluated by the rule’s current version. The second card depends on the action:

Card	Shows
Results	How many records the rule evaluated. While a run is in progress, it shows the run’s progress instead.
Pass rate	On an alert rule, the share of records that passed, with how many passed, alerted and were dismissed. Dismissed records are left out of the rate.
Outcome	On a substitute rule, how many values it substituted and how many it left as measured.
Last evaluated	When the rule last finished evaluating. When proposals are waiting, this card becomes Waiting on approval, with how many are waiting and a Review button.

The counts are rebuilt in the background, so they can take a few minutes to catch up after a run finishes.

Tabs

Evaluated Records lists the records the rule evaluated, filtered to alerts at first. Use Result to show the rest. On a substitute rule the choices are Substituted, Measured, and, with Require approval on, Waiting on approval.
Runs lists each time the rule evaluated data. See below.
Activity lists the edits made to the rule, with who made them and when.

Runs

Each row is one run: when it Started, what Triggered by it (the rule being saved, new data and its source, or someone evaluating a period), and its Result, such as how many records it evaluated, how many new alerts it raised and how many it cleared. A run is Running, Completed, Failed, Superseded (replaced by a newer run before it finished; what it had already written stays), Reverting, Reverted or Revert failed. Evaluate a period starts a run over a range of dates you pick, the last 30 days by default. Before you confirm, it shows how many records it would evaluate, and warns if the range falls partly or wholly outside the rule’s effective period. The run overwrites the results in that range, except that alerts dismissed against the rule’s current version stay dismissed and records in a filed report keep their result. It replaces any evaluation already running for the rule, which cannot be resumed, and is refused while a revert is in progress. The icons at the end of a row act on that run:

View changed records switches to Evaluated Records, filtered to the records the run changed.
Revert run undoes what the run wrote. Results it created are deleted, results it changed go back to their previous state, and on a substitute rule the values it corrected go back to what they were before the run. The Revert this run? dialog counts each of these before you confirm.
Retry run appears on a failed run that wrote nothing, and opens Evaluate a period with the same range.
Retry revert appears when a revert stopped part-way, and continues from where it stopped.

A revert leaves some records alone and lists them in the dialog under Refused, and why: alerts a person dismissed after the run, results and corrections on records in a filed report, results a later run has since replaced, and values a person has corrected since. Revert run is greyed out while the run is still going, or while another evaluation or revert is running for the rule; hover it to see which. A revert runs in the background, and no new run for the rule can start until it finishes. A revert does not change the rule. The next time the rule evaluates those records, for example when you evaluate the period again, it raises or corrects them again. To stop that, edit the rule or shorten its effective period first.

Editing a rule

Open a rule from the Data Rules list and click Edit. Editing uses a single form rather than the wizard, with the same fields in the same order. Changing the condition saves a new version and re-evaluates matching records inside the effective period. The new version’s results replace the rule’s existing alerts, so earlier alerts, including any you dismissed, are reset. Changing the effective dates saves a new version too, and so does changing the substitution methods, What to flag (What to correct), or, over the API, the action. The same reset applies to each, so plan on re-triaging a rule’s alerts after any of these edits.

Switching between Alert and Substitute

The edit form does not offer the action, so a rule cannot be switched between Alert and Substitute in the app. Create a new rule with the action you want instead. A new rule with the same condition as an existing one is refused while their effective periods overlap, with A rule with the same expression already exists and a View existing rule link. So first either delete the old rule, which removes its alerts, or set the old rule’s Effective to to end before the new rule’s Effective from, which keeps its history. Through the API, Update a rule accepts a new action, which saves a new version of the same rule.

Turning approval on or off

Switching Require approval on or off does not save a new version. Switching it off withdraws every proposal still waiting on the rule: nobody approved them, so those data points keep their measured values and are not corrected unless you evaluate the period again from the rule’s Runs tab. The confirmation counts them before you commit.

Variables in an alert message render as the configured data point type name. The message is stored when you save, so this applies to rules created or re-saved from now on. Existing rules keep the message they were saved with.

Stopping or deleting a rule

Action	Effect
Shorten the effective period	Set or pull in the Effective to date so the rule stops evaluating new records. The rule and its history stay in the project, and its active alerts are re-evaluated against the new period, which resets any dismissals. Use when the rule has served its purpose for past data.
Delete	Permanently removes the rule along with all of its evaluations and alerts. Use when the rule was a mistake or you no longer need it. Values the rule corrected stay corrected and keep the rule’s name and ID in their history. To put them back first, use Revert a rule’s corrections in the API. A delete is refused while an evaluation or revert is running for the rule, so try again once it finishes.

Overview

Production Accounting

Data Collection

Data Rules

Reporting

Inventory

Account Admin

Portfolio

Before you start

Step-by-step

Acting on the whole window

If the action is Substitute

Holding corrections for approval

If the action is Alert

Rules that run on demand

How rules appear in the list

The rule page

Counts

Tabs

Runs

Editing a rule

Switching between Alert and Substitute

Turning approval on or off

Stopping or deleting a rule

​Before you start

​Step-by-step

​Acting on the whole window

​If the action is Substitute

​Holding corrections for approval

​If the action is Alert

​Rules that run on demand

​How rules appear in the list

​The rule page

​Counts

​Tabs

​Runs

​Editing a rule

​Switching between Alert and Substitute

​Turning approval on or off

​Stopping or deleting a rule

Before you start

Step-by-step

Acting on the whole window

If the action is Substitute

Holding corrections for approval

If the action is Alert

Rules that run on demand

How rules appear in the list

The rule page

Counts

Tabs

Runs

Editing a rule

Switching between Alert and Substitute

Turning approval on or off

Stopping or deleting a rule