Architecture Overview

EZY Integrations connects source systems (such as an ERP or e-commerce store) to target systems (such as EZY Portal or a flat file) by routing data through a shared, neutral format called the canonical entity. This design means you can add a new source or target connector without rewriting every existing mapping — all connectors speak the same intermediate language.

Every integration is configured as a job that links a source connection profile to a target connection profile using one or more mapping configurations. When a job runs, data travels through five pipeline stages: ingest, normalize, transform, execute, and finalize.

How data flows

flowchart LR
    A[Source System] -->|Extractor reads data| B[Raw Records]
    B -->|Normalizer converts| C[Canonical Entity]
    C -->|Transformer shapes| D[Target Payload]
    D -->|Connector writes| E[Target System]
    E -. optional writeback .-> A

The canonical entity is the pivot point of this design. It is a neutral record format that every connector understands. The source connector extracts raw data and converts it to a canonical entity; the target connector reads that canonical entity and produces the payload the target system expects. No source talks directly to any target.

The five pipeline stages

Each record passes through five stages in order. If a stage fails, the record is retried automatically. After all retries are exhausted, the record moves to the Dead Letter Queue for manual review.

Stage	What happens
Ingest	The job reads records from the source system using the connection profile credentials and the extraction rules in the mapping config.
Normalize	Raw source data is converted into a canonical entity. This stage applies type coercions and required-field validation.
Transform	The canonical entity is shaped into the exact payload the target system expects, applying field mappings, value transformers, and static fields from the mapping config.
Execute	The transformed payload is sent to the target system. The connector handles create-vs-update reconciliation.
Finalize	The run outcome is recorded. Sync cursors are updated so the next run picks up only new or changed records.

See Pipeline Stages for a full breakdown of each stage and what to do when a stage fails.

Incremental sync and cursors

Most source connectors support incremental sync: instead of re-reading every record on each run, the system tracks a cursor — typically a last-modified timestamp — and only fetches records that changed since the previous run. The cursor value is saved at the end of each successful finalization stage and read at the start of the next ingest stage.

The cursor column is configured in the extraction block of your mapping configuration. See Mapping Configuration for details.

Building blocks at a glance

Building block	What it is
Connection profile	Saved credentials for one system (source or target).
Mapping configuration	JSON document that controls extraction, normalization, and transformation rules for one entity type.
Job (instance)	Links a source profile to a target profile and holds one or more mapping configurations.
Run	One execution of a job — produces a result of success, partial success, or failure.
Entity type	The kind of record being moved: item, business partner, order, and so on.
Canonical entity	The neutral intermediate format all connectors share.
Dead Letter Queue	Holds records that failed all automatic retries, ready for manual replay.

Related

• Pipeline Stages — Detailed breakdown of each stage, failure behavior, and retry logic.
• Entity Types — Full list of supported entity types and which connectors handle them.
• Mapping Configuration — How to author the JSON document that controls extraction, normalization, and transformation.