Property Calculator Configuration Reference

Overview

Top-Level Structure

Configuration
├── Calculation Rules          ← Class groups with property calculations
├── Value List Operations      ← Validation for value list items
├── Background Operations      ← Scheduled tasks and state transitions
└── Settings                   ← Global application settings

The individual calculation modes and condition types referenced throughout this page have their own dedicated reference pages: Calculation Modes and Conditions.

Calculation Rules (Class Groups)

Each entry in Calculation Rules defines a Class Group — a set of property calculations, error cases, and related object update rules that apply to objects matching specific criteria.

Class Group Settings

Class vs. Custom Group

Use Class (default) when your rules should apply to all objects of a specific M-Files class. This is the simplest and most common configuration.

Use Custom Group when you need more flexible matching, such as:

• Rules that apply across multiple classes
• Rules based on property values (e.g., only objects where Status = Active)
• Rules based on object type without class restriction
• Complex multi-condition matching

Example: A Custom Group with condition “Object Type = Document AND Property ‘Department’ = Finance” would apply to all Finance documents regardless of their class.

Event Handler Timing

This setting controls when Property Calculator runs during the check-in process:

⚠️ Consequences of BeforeCheckInChanges:

• Your calculated values may be overwritten by subsequent event handlers
• The object may be in an intermediate state (other automations haven’t run yet)
• This timing is marked as Experimental — use only when specifically needed

Rule Execution Order

Property calculation rules within a group execute sequentially from top to bottom. Earlier rules’ results are available to later rules. This means you can:

1. Calculate an intermediate value in Rule 1
2. Use that intermediate value in Rule 2’s expression

Example: Rule 1 sets PD.Subtotal = quantity × price, then Rule 2 sets PD.Total = %PROPERTY_{PD.Subtotal}% × 1.24 (adding VAT).

Error Cases

Error cases define blocking rules that prevent users from performing specific actions when conditions are met. They are configured within each Class Group.

Error Case Settings

General Error Message

The parent Class Group has a General Error Message field. When set, this message is prepended to all error case messages in the group — useful for context like “Invoice validation failed:”.

Examples

Prevent check-in without required approval:

Error Name:    "RequireApproval"
Error Message: "This document requires approval before check-in. 
                Please set the Approved By property."
Block Modification: ✅
Conditions:    Property PD.Status = "Pending Approval" 
               AND Property PD.ApprovedBy is empty

Block deletion of active contracts:

Error Name:    "PreventActiveContractDeletion"
Error Message: "Active contracts cannot be deleted. 
                Change status to Terminated first."
Block Delete:  ✅
Block Destroy: ✅
Conditions:    Property PD.Status = "Active"

Allow scripts but block users from modifying archived records:

Error Name:    "ArchiveProtection"
Error Message: "This record is archived and cannot be modified."
Block Users Only: ✅
Block Modification: ✅
Conditions:    Property PD.Status = "Archived"

Value List Operations

Configure validation rules for value list items.

Value List Validation

Example: Ensure department codes follow the format “DEPT-XXX”:

• RegExp: ^DEPT-[A-Z]{3}$
• Error Message: “Department code must be in format DEPT-XXX (e.g., DEPT-FIN)”

General Settings

Global settings that affect all Property Calculator operations.

Loop Detection

Prevents infinite calculation loops that can occur when related object updates create circular dependencies (A updates B, B updates A, A updates B…).

What happens when a loop is detected:

1. The offending update or state transition is skipped
2. A warning/error is logged (and surfaced in the Status Report if enabled)
3. The object may appear as “stuck” on the dashboard if its updates keep being retried

Loop detection reads the object’s version history at runtime — there is no persistent flag in NVS. Once the runaway versioning stops, the object recovers on its own.

For tips on adjusting these thresholds (e.g. for bulk imports), see Advanced / Operational Settings at the end of this document.

Status Reporting

In plain terms: this is an automated health check — if enabled, Property Calculator periodically writes a summary of stuck or errored objects so admins can spot problems without digging through logs.

Configures automated status reports for monitoring application health. When enabled, a report is written to a designated vault object’s Comment property (see Troubleshooting).

Background Update (pipeline, retry & dead-letter)

In plain terms: Property Calculator processes related-object updates and state transitions in the background rather than immediately, so check-in isn’t slowed down. These settings control how often that background work runs, how much it does per pass, and how it handles updates that fail (automatic retries, and eventually giving up and setting them aside).

Global settings that control the asynchronous processing pipeline. See Background Operations for how these fit together.

For the overflow buffer’s fixed structural limits (not configurable), see Advanced / Operational Settings at the end of this document.

Related Object Update Settings

The related-object throttle settings (Do not update immediately if modified in past and Version offset for modification check) are fully documented in the Background Update table above — see also Background Operations.

Configuration History

Advanced / Operational Settings

This section collects deeper tuning rationale for edge cases. It is not needed to complete a basic configuration — the settings themselves are documented in their normal locations (Loop Detection and Background Update above); this is background on why and when to adjust them.

Loop Detection tuning

If you have legitimate use cases that create many versions in a short time (e.g. bulk imports), increase Max server versions per 24h so they aren’t mistaken for a loop. To detect genuine loops faster (at the risk of more false positives on legitimate rapid changes), decrease the State chain time window.

Background Update overflow buffer internals

The hot-queue overflow buffer has fixed structural limits that are not configurable: 10,000 entries per segment, 10 segments, a 100,000-object hard cap, and an 80,000-object warning threshold. These exist to bound memory use under extreme backlog and are provided here for reference only — in normal operation, the Max number of objects to update in one run and When the overflow buffer is full settings (see the Background Update table) are what admins tune day to day.