External Integrations — Revisio

Business Context

Business-Level Definition

Revisio is an external accounting/invoicing system operated by a third party (SkyCom online s.r.o.), used by one specific EM3 client — Město Slaný (client 46, confirmed active, licence valid to 2028-11-15). For this client, Revisio is the system of record for manually-entered meter readings and invoices; EM3 mirrors that data in one direction so it's usable alongside every other client's data (reports, charts, validation) without the client having to enter it twice.

The integration is invisible in the EM3 UI by design — there is no manual-entry form or button involved. It runs unattended on a nightly schedule and simply keeps EM3's copy of this one client's readings and invoices in sync with Revisio.

Requirements Definition

• Invoices and readings entered into Revisio for client 46 must appear in EM3 without manual re-entry
• Updates and deletions made upstream in Revisio must be reflected in EM3 on the next sync — EM3 never becomes the source of truth for this data
• The integration must not affect any other client — it is scoped to client 46 only, not a generic multi-client mechanism
• Sync failures must be visible to whoever operates the integration, without requiring a client-facing error surface (this client never interacts with the sync directly)

Acceptance Criteria

Not explicitly enumerated in the source material as a separate section; the Requirements Definition above functions as the acceptance bar for this integration.

Loom Link

N/A — not available in the source material.

Technical Context

User Stories / Use Cases

Nightly sync: A scheduled job runs nightly and queries Revisio's database for records belonging to client 46. New records become new invoice/reading rows in EM3; changed records update the EM3 copy; deleted upstream records are removed from EM3.

Not further elaborated as end-user-facing use cases in the source material — this integration has no UI surface (see Business-Level Definition).

UI/UX Design

None — the integration is invisible in the EM3 UI by design.

Functional Requirements

What Revisio provides

EM2 connects directly to a separate Revisio-operated database and reads records of type INVOICING. Each record carries the data needed to reconstruct an invoice or reading for a specific gauge, including per-segment consumption figures (tariff-split values) and cost. There is no Revisio-exposed API in this integration — EM2 reads Revisio's database directly, not the other way around.

Behaviour specification

• A scheduled job runs nightly and queries Revisio's database for records belonging to client 46.
• For each Revisio record: if it's new, a corresponding invoice (with its invoiceValue rows) or reading is created in EM3. If it already exists and has changed upstream, the EM3 copy is updated. If the upstream record has been deleted, the corresponding EM3 record is removed.
• Direction is strictly one-way: Revisio → EM3. EM3 never writes back to Revisio. (A reverse direction — EM3 exposing an API for Revisio to pull remote water-meter readings — was originally discussed but confirmed never built; no outbound flow exists in any form.)
• The link between an EM3 record and its originating Revisio record is tracked internally (see Implementation Notes) — it is not a column on invoice or reading themselves, so the rest of the domain model stays free of this client-specific detail.

Non-Functional Requirements

Not covered in source material beyond the nightly-schedule cadence.

Implementation Notes

• The link between an EM3 record and its Revisio counterpart is stored in a small internal sync table, generic across entity types (entityType + entityId + revisioRecordId) rather than as a column on invoice/reading — this keeps the domain entities free of integration-specific detail and allows the same mechanism to cover both invoices and readings without duplicating it per entity.
• Reconciliation on each run: existing links are used to detect upstream changes (update) and upstream removals (delete in EM3). New Revisio records with no existing link are treated as newly created in EM3.
• Scheduling and error visibility: sync failures must be surfaced somewhere an operator can see them (EM2 had an admin screen listing import errors) — the equivalent for EM3 is not yet designed; flagged here as a gap to close when this integration is implemented, not a v1 blocker for Invoice/Reading Management themselves.
• Scope is hard-limited to client 46 — this is not a generic external-accounting-system connector. If a future client needs a similar integration with a different system, that's new work, not a configuration of this one.

API Analysis

No EM3-exposed API — the integration reads Revisio's database directly (see "What Revisio provides" above). No endpoint table applies.

Domain Model (ER diagram) & Data Attribute Table

No ER diagram in source material. Entities involved (Confluence entity pages, not yet migrated into this repo's Entity DAT catalog):

• invoice / invoiceValue — target of synced Revisio invoice records
• reading — target of synced Revisio reading records
• an internal sync-link table (entityType + entityId + revisioRecordId) — see Implementation Notes; not a formally named entity in the source page

Data

Not covered in source material beyond the client-46 scoping described above.

Test Data

N/A — not covered in source material.

Logging

.info

• Sync run started/completed, with counts of records created/updated/deleted

.warn

• Individual record sync failure (record identified, reason), without failing the entire run

Monitoring

Sync failure visibility is an open gap — see Implementation Notes above; not a v1 blocker for Invoice/Reading Management.

Caching

N/A — not covered in source material.

Backward Compatibility and Migration

N/A — not addressed in the source Confluence page beyond describing this as a continuation of an existing EM2 integration pattern (direct database read from Revisio).

Legal Context

N/A — not addressed in the source Confluence page; migrated as a reference copy without new legal analysis. Note: this integration involves a data-sharing arrangement with a named third-party operator (SkyCom online s.r.o.) for a specific named client — any contractual/data-processing agreement terms were not captured in the source page and should be confirmed separately.

Cybersecurity Considerations

N/A — not addressed in the source Confluence page; migrated as a reference copy without new security analysis. Note: this integration reads directly from a third-party operated database containing invoicing/reading data for a named client — data-privacy and access-control implications should be reviewed when Cybersecurity is formally analysed for this integration.

Risk Assessment

N/A — not addressed in the source Confluence page; migrated as a reference copy without new risk analysis.

Auditing, Reporting & Measurement

N/A — not addressed in the source Confluence page; migrated as a reference copy without new analysis.

---