Skip to content

IIMS – Provider & Integration Architecture

Purpose

This document describes how IIMS integrates with external systems in Current, based on the current iims‑api implementation and Flutter UI.

It explains:

  • The adapter and routing architecture actually implemented today
  • The scope and limitations of Current integrations
  • The roadmap and recommended extensions for Planned

The goal is to provide an accurate and auditable reference for architects, engineers, and product owners.

1. Integration Philosophy (Current)

1.1 Integrate, don’t replace

IIMS does not replace operational systems such as monitoring, ticketing, or identity platforms.

In Current:

  • Monitoring systems continue to collect metrics and generate alerts
  • Ticketing systems continue to manage workflows
  • Identity systems continue to manage authentication

IIMS acts as a coordination and information layer above them, unifying:

  • Inventory context (sites, assets)
  • Routing and configuration
  • Alerts, incidents, maintenance, and tickets

1.2 Provider independence (Current scope)

In Current, IIMS is provider‑agnostic by design, but actively supports:

  • Monitoring provider: Zabbix (primary implementation)
  • Ticketing provider: Zammad
  • Identity provider: Keycloak

The internal domain model never depends on provider‑specific schemas.

Notes:

  • Prometheus and additional providers are planned but not yet active in Current
  • Multi‑provider operation is architecturally supported, but only partially exercised

2. Core Integration Components

2.1 Monitoring Target

A Monitoring Target represents a configured connection to one monitoring backend.

Examples in Current:

  • One Zabbix server

Role:

  • Stores endpoint, credentials, and provider type
  • Entry point for provisioning, telemetry, alerts, and maintenance sync

Target answers the question: Which monitoring system does this asset use?

Current notes:

  • Multiple targets are supported in the model
  • Routing between multiple targets is supported logically
  • Active production usage focuses on Zabbix targets

Planned Planned:

  • Activate Prometheus targets
  • Mixed‑provider environments per site
  • Provider capability discovery and feature flags

2.2 Collector

A Collector represents a proxy or agent pool used for monitoring data collection.

Examples in Current:

  • Zabbix proxy groups

Role:

  • Defines where monitoring traffic originates
  • Controls routing of assets to proxies
  • Applies routing constraints (site, tags, asset type, capacity limit)

Collector answers the question: From where is this asset monitored?

Current behavior:

  • Collectors are selected using routing constraints and static policies
  • Capacity is tracked but not dynamically optimized
  • Routing is deterministic and policy‑driven

Planned Planned:

  • Capacity‑aware routing and load balancing
  • Collector health monitoring and automatic failover
  • Geo‑aware and SLA‑aware routing policies

3. Target and Collector Routing Model

3.1 Routing Principles (Current)

Routing determines:

  • Which monitoring target is assigned to an asset
  • Which collector performs the actual collection

Routing decisions are based on:

  • Asset configuration
  • Site defaults
  • Collector routing constraints (allowed sites, tags, asset types, capacity)

Current routing characteristics:

  • Policy‑driven and deterministic
  • Site‑aware
  • No dynamic rebalancing or failover

3.2 Routing Flow (Current)

Typical provisioning flow:

  • An asset is selected for monitoring
  • IIMS resolves the monitoring target (asset → site → default)
  • IIMS evaluates collector routing constraints
  • One collector is selected
  • The request is routed to the provider adapter

This ensures:

  • Correct backend selection
  • Policy‑driven routing
  • Site‑aware monitoring

Planned Planned:

  • Multi‑candidate routing with scoring
  • Automatic rerouting on collector failure
  • Capacity and latency aware selection

4. Adapter Pattern

4.1 Purpose of Adapters

Each external provider is integrated through an adapter layer.

An adapter:

  • Translates IIMS domain operations into provider‑specific API calls
  • Normalizes provider responses into IIMS domain objects

Adapters isolate the core platform from vendor APIs and schemas.

4.2 Adapter Responsibilities (Current)

Implemented adapter responsibilities include:

Monitoring adapters (Zabbix):

  • Asset provisioning and template binding
  • Telemetry and interface discovery
  • Alert ingestion and normalization
  • Alert actions (acknowledge, close, suppress)
  • Maintenance synchronization

Ticketing adapters (Zammad):

  • Ticket creation from incidents
  • Ticket status queries
  • Comment and closure synchronization (limited)

Notes:

  • Adapters expose only normalized domain objects
  • Provider‑specific IDs are stored only in external reference fields

Planned Planned:

  • Prometheus adapter activation
  • Bi‑directional ticket state synchronization
  • Multi‑ticket per incident support
  • Provider‑side maintenance automation

5. Provider Registry and Routing Layer

5.1 Provider Registry (Current)

IIMS maintains a central provider registry that:

  • Registers adapters at startup
  • Resolves adapters by provider type
  • Provides a stable interface to domain services

This registry is used by:

  • Monitoring routers
  • Ticketing routers
  • Maintenance synchronization workers

5.2 Routing Layer

The routing layer:

  • Receives domain requests (provisioning, telemetry, alert sync, ticketing)
  • Resolves monitoring target and collector
  • Selects the correct adapter
  • Forwards the request to the provider

This layer hides all provider complexity from:

  • Domain services
  • UI and workflows

Planned Planned:

  • Routing explanation and simulation APIs (for debugging and UI)
  • Multi‑provider routing strategies

6. Multi‑Provider Strategy

6.1 Current Scope

Architecturally supported:

  • Multiple monitoring targets
  • Multiple collectors
  • Multiple ticketing targets

Actively implemented in Current:

  • Zabbix as primary monitoring provider
  • Zammad as primary ticketing provider

Notes:

  • Different sites can use different providers, but this is not heavily exercised yet

6.2 Migration and Co‑existence (Planned Direction)

Because providers are abstracted:

  • New providers can be added without changing domain logic
  • Old providers can be retired gradually
  • UI and workflows remain unchanged

Planned Planned:

  • Parallel Zabbix + Prometheus operation
  • Cross‑provider alert correlation
  • Migration assistants and data reconciliation tools

7. Failure Handling and Resilience

Current behavior:

  • Provider errors are isolated per request
  • Failures are recorded in sync state and activity logs
  • Background workers retry failed sync operations

Limitations in Current:

  • No automatic provider failover
  • No health‑based routing decisions

Planned Planned:

  • Provider health monitoring
  • Automatic failover between targets
  • Degraded‑mode routing strategies

8. Security and Secrets Management

Current principles:

  • Provider credentials stored in Vault / secret store
  • No credentials stored in plain text
  • Secrets injected at runtime

Authentication between:

  • Users → IIMS: handled by Keycloak (OIDC)
  • IIMS → providers: isolated service credentials

Planned Planned:

  • Automated secret rotation
  • Per‑target credential versioning
  • Audit trails for credential usage

9. Extending IIMS with a New Provider

To add a new provider in Current:

  • Implement a new adapter using standard provider interfaces
  • Register the adapter in the provider registry
  • Configure a new monitoring or ticketing target
  • Optionally define collectors and routing constraints

No changes are required in:

  • Core domain model
  • User interface
  • Incident and maintenance workflows

10. Planned Roadmap for Integration Architecture

Recommended Planned focus areas:

  1. Multi‑provider activation (Zabbix + Prometheus)
  2. Capacity‑aware and health‑aware routing
  3. Automatic provider failover
  4. Cross‑provider alert correlation
  5. Bi‑directional ticket synchronization
  6. Provider capability discovery API
  7. Routing simulation and debugging UI

11. Summary

In Current, the provider and integration architecture of IIMS delivers:

  • Clean adapter abstraction
  • Central provider registry and routing
  • Target and collector separation
  • Stable Zabbix and Zammad integrations

This provides a strong foundation for scalable, provider‑independent operations.

Future phases extend this foundation with:

  • Intelligent routing
  • Automated failover
  • Multi‑provider correlation
  • Advanced synchronization and migration tools

These enhancements build on the Current architecture without breaking existing workflows.