Rules & Business Rules

MapexOS provides an enterprise-grade automation layer designed for high-volume event pipelines, multi-tenant governance, and auditable execution.

The platform separates reusable logic from tenant-specific configuration using a two-layer model:

• Rules — reusable automation templates (built once, reused across orgs)
• Business Rules — configured instances of a Rule, scoped to specific organizations and assets

This pattern enables consistent automation at scale while allowing each tenant to customize thresholds, recipients, filters, and actions—without duplicating logic.

Applies to v1.0.0 — Redis-backed state, visual rule builder, test mode, technical + communication actions, and persistent logs (EVA-indexed).

---

Conceptual model

Rule (template)

A Rule defines the automation blueprint:

• Conditional logic (single conditions and nested groups)
• Reusable actions (state, logs, external executions)
• Optional parameters (resolved by the Business Rule)

Example (template):

Rule: "High Temperature Alert"
When: temperature >= {threshold}
Do: notify {channel}

Business Rule (configured instance)

A Business Rule is a scoped deployment of a Rule, bound to:

• Organization scope (tenant isolation + optional child scope)
• Asset filters (template, tags, identifiers)
• Parameters (thresholds, destinations, recipients)
• Operational settings (timezone, enablement, debugging)

Example (instance):

Business Rule: "Factory Alpha High Temp"
Template: "High Temperature Alert"
Parameters: threshold = 80, channel = "#ops-alerts"
Scope: org "Factory Alpha" (+ children)

Rule vs Business Rule

Aspect	Rule (template)	Business Rule (instance)
Logic	Generic reusable	Tenant-configured
Parameters	Placeholders	Concrete values
Scope	Global / org template	Org-specific execution
Governance	Shared across orgs	Owned by the tenant

---

UI configuration overview (Edit Rule)

In MapexOS, a Business Rule is configured through five tabs:

Tab	Purpose
General	Identity, enablement, sharing, and timezone behavior
Variables	Rule Variables (state) and Capture Fields (logging schema)
Actions	Action catalog (State, Log, Exec) reused by conditions/groups
Rules	Visual builder: conditions, groups, operators, and action attachments
Debug	Test Mode execution with simulated events and trace output

Enterprise note
Treat Rules as production artifacts. Use naming conventions, versioning, and controlled sharing to ensure consistency across tenants and environments.

---

General tab

Basic information

Setting	Description
Name	Business Rule identifier
Description	Operational purpose and usage notes
Rule enabled	When enabled, the rule is active and processes events
Mark as shared template	Makes this Rule available for child organizations

Sharing across the organization hierarchy

When Mark as shared template is enabled, the Rule can be reused by child organizations. This supports standardized policies such as:

• “All factories must emit incident alerts above threshold”
• “Child sites inherit the same escalation workflow”
• “Subsidiaries reuse centrally defined compliance rules”

Timezone behavior

Timezone selection affects any operator and action that evaluates or constructs date/time values.

Type	Description
Fixed timezone	All date/time comparisons use a single timezone (e.g., UTC)
Dynamic timezone	Timezone resolved by tenant context or event metadata (when supported)

Enterprise note
Timezone alignment is critical for schedules, SLAs, “business-hours” alerts, and regional compliance reporting.

---

Variables tab

The Variables tab has two sections: Rule Variables and Capture Fields.

Rule Variables (stateful execution)

Rule Variables are typed state values persisted via Redis and designed to track context across events.

They enable:

• Stateful automation (counters, incident flags, cooldowns)
• Autocomplete in the Rule Builder and Actions
• Type safety with explicit defaults

Property	Description
Name	Variable identifier (valid JavaScript identifier)
Type	number, text, boolean
Default Value	Initial value when the state key is missing

Example variables:

Variable	Type	Default	Enterprise use case
counter	number	0	Escalation after N occurrences
incidentOpen	boolean	false	Incident lifecycle control
lastAlertAt	text	""	Cooldown / deduplication

Enterprise note
Rule Variables are not just “local variables”. They represent durable state used to build deterministic behavior across distributed event streams.

Capture Fields (persistent logging schema)

Capture Fields define the log schema used by Log actions. Each field becomes queryable for auditing and reporting.

Capture Fields support EVA-indexed storage, which enables:

• Operational dashboards (counts and trends)
• Incident forensics (“what happened before this alert?”)
• Compliance evidence (“which rule fired, when, and why?”)

Property	Description
Field Name	Key stored in the log record
Type	number, text, boolean, date (depending on UI support)
Source	Where the value comes from: Event, State, Variable, Literal

---

Value sources (Event, State, Variable, Literal)

Across conditions, actions, and log mapping, MapexOS uses a consistent value-source model:

Source	Description	Enterprise benefit
Event	Values from the incoming Standard Event	Template-aware field autocomplete
State	Values from Rule Variables (Redis)	Stateful, deterministic automation
Variable	Values from Business Rule parameters	Multi-tenant customization without cloning
Literal	Fixed values defined directly in the rule	Explicit and predictable comparisons

Autocomplete behavior

• Event values are suggested from the Asset Template structure (when available).
• State values are suggested from defined Rule Variables.
• Variable values represent tenant-configurable parameters (Business Rule configuration).
• Literal values are manually typed and strongly recommended for constants.

---

Actions tab

Actions define “what the rule can do”. They are reusable and can be attached to:

• A specific condition
• An entire group

MapexOS supports three action categories:

1) State actions

State actions manipulate Rule Variables (Redis-backed state).

Action	Description	Example
Increment	Adds a value to a numeric state	counter += 1
Decrement	Subtracts a value from a numeric state	retries -= 1
Set	Assigns/overwrites a state value	incidentOpen = true

UI mapping example:

Increment State
- Variable: counter
- Source: Literal
- Increment by: 1

2) Log actions (persistent capture)

Log actions persist structured values for later analysis and reporting.

Typical flow:

Log Action
└── Save Capture Data
    └── Map values to Capture Fields

Example mapping:

Capture Field	Source	Example
temperature	Event	event.data.temperature
assetId	Event	event.metadata.assetId
counter	State	state.counter
threshold	Variable	params.threshold

Enterprise note
Log actions are the foundation of auditability. In regulated environments, treat capture fields as part of your compliance evidence strategy.

3) Exec actions (technical + communication)

Exec actions interact with external systems and notification channels.

Category	Examples
Technical	HTTP, MQTT, NATS, Kafka, RabbitMQ, WebSocket
Communication	Email, Slack, Microsoft Teams

Execution control

Exec actions support operational controls:

Setting	Options	Purpose
Execution Mode	Sequential, Parallel	Controls how a group of actions executes
Error Handling	Continue, Stop	Controls behavior when an action fails

Slack example (conceptual):

{
  "type": "slack",
  "config": {
    "channel": "#ops-alerts",
    "message": "Alert #{{state.counter}}: temperature {{event.data.temperature}} on {{metadata.assetId}}"
  }
}

---

Rules tab (visual builder)

The Rules tab is where the business logic is assembled using:

• Groups (containers with logical operators)
• Conditions (comparisons using sources and operators)
• Attached actions (condition-level or group-level)

Groups (logical operators)

Groups combine conditions through a selected operator:

Group Type	Meaning
All conditions	AND — all conditions must match
Any condition	OR — at least one condition must match
Not all conditions	NAND — not all may be true
Not any condition	NOR — none may be true

Condition structure

Each condition compares:

• Left side: value source + field selection
• Operator: equals, greater-than, between, etc.
• Right side: value source + value/field selection

Conceptually:

LEFT (source + field)   OPERATOR   RIGHT (source + value)

Attaching actions

Actions can be attached at two levels:

Level	Behavior
Condition	Executes only if that condition matches
Group	Executes if the group resolves to true

Enterprise note
Prefer group-level actions for consistent, auditable behaviors. Use condition-level actions for incremental state updates and fine-grained workflows.

---

Debug tab (Test Mode)

MapexOS includes Test Mode for validating rules safely before production rollout.

Test Mode flow

1. Open Debug tab (or enable Test Mode toggle)
2. Select an Asset Template (defines expected payload structure)
3. Enable Test Mode
4. Click Start
5. Review evaluation trace, state updates, and action results

What Test Mode validates

Capability	What it verifies
Condition logic	Operators, groups, and comparisons behave correctly
State behavior	Variables increment/set as expected (Redis semantics)
Capture logs	Values map correctly into Capture Fields
Exec actions	External calls are triggered (use sandbox endpoints)

Enterprise note
Test Mode uses the same engine and evaluation semantics as production. The primary difference is the event source (simulated vs live).

---

Runtime execution model

At runtime, MapexOS evaluates rules as events arrive:

1. Receive Standard Event
2. Resolve tenant scope (org + hierarchy, if applicable)
3. Load Business Rule configuration
4. Load Rule Variables (state) from Redis
5. Evaluate groups/conditions using value sources
6. Execute actions in the configured order:
   State → Log → Exec (as configured)
7. Persist logs (when enabled) for audit/query

State scoping (collision safe)

State keys are scoped to avoid collisions across tenants and rules:

state:{orgId}:{businessRuleId}:{variableName}

Example:

state:org-123:br-456:counter
state:org-123:br-456:incidentOpen

---

Enterprise patterns

Cooldown / deduplication

Prevent alert fatigue by throttling notifications:

Variables:
- lastAlertAt (text)

Rule:
IF event.temperature >= params.threshold
AND now() - state.lastAlertAt > params.cooldownSeconds

Actions:
- Exec: Notify channel
- State: Set lastAlertAt = now()

Escalation after N occurrences

Trigger escalation only after repeated events:

Variables:
- counter (number)

Rule:
IF event.status equals "critical"
  → State: counter += 1

IF state.counter >= params.escalateAfter
  → Exec: Escalate
  → State: counter = 0

Incident lifecycle (open/close)

Create deterministic incident handling:

Variables:
- incidentOpen (boolean)

Open:
IF event.status equals "critical"
AND state.incidentOpen equals false
  → Exec: Open ticket
  → State: incidentOpen = true
  → Log: "incident_opened"

Close:
IF event.status equals "ok"
AND state.incidentOpen equals true
  → Exec: Close ticket
  → State: incidentOpen = false
  → Log: "incident_closed"

---

Governance and sharing

Visibility and reuse

Scope	Description
System Rule	Provided by MapexOS, available across the platform
Organization Rule	Defined by a tenant, private by default
Shared Rule	Organization Rule shared with child organizations

To share a rule, enable Mark as shared template for use by child organizations in the General tab.

Change management recommendations

• Use structured naming: ALERT - Temperature - v1
• Prefer parameterization over cloning
• Validate in Test Mode before enabling
• Add Capture Fields for audit-critical flows
• Keep Exec actions idempotent when possible

---

Best practices

Practice	Recommendation
Define state upfront	Create Rule Variables before building complex logic
Use meaningful names	alertCounter instead of c1
Prefer parameters	Use Variable source for thresholds and channels
Throttle notifications	Cooldowns prevent alert storms
Log for auditability	Capture Fields provide long-term traceability
Test before enabling	Use Test Mode with realistic payloads
Monitor failures	Review Exec action outcomes and delivery rates

---

Next steps

• Events & Pipeline — Stream routing, storage, and retention (TTL)
• Assets & Templates — Template scripts and EVA field extraction
• Roles & Permissions — Governance model and access control