Skip to content
EZY Wiki

Pipeline Stages

Every record that EZY Integrations processes moves through five stages in order. Understanding these stages helps you diagnose where a failure occurred and what action to take. Each stage is independently retried on failure, and a record that exhausts all retries is moved to the Dead Letter Queue for manual review.

Stage flow

Section titled “Stage flow”
flowchart LR
    A[Ingest] --> B[Normalize]
    B --> C[Transform]
    C --> D[Execute]
    D --> E[Finalize]
    D -- failure after retries --> F[Dead Letter Queue]
    F -- manual replay --> A

Stage reference

Section titled “Stage reference”
StagePurposeWhat can fail hereUser remedy
IngestReads records from the source system using the connection profile credentials and the extraction rules in the mapping config. Advances the sync cursor when complete.Authentication failure; source system unreachable; invalid extraction query; no records match the cursor window.Check the connection profile credentials; verify the source system is running; review the extraction block in the mapping config.
NormalizeConverts raw source data into the canonical entity format. Applies type coercions and validates required fields.A required field is null or empty; a type conversion fails (for example, a non-numeric value in a decimal field); the entity type is not recognized.Review the normalization block of your mapping config; check that required source fields are populated; verify the entity type name matches exactly.
TransformShapes the canonical entity into the exact payload the target system expects. Applies field mappings, value transformers, static fields, and conditional mappings from the mapping config.A transformer receives an incompatible value; a required target field has no mapping; an invalid target path is specified.Review the transformation block; check transformer options; ensure every required target field has a mapping or a static field entry.
ExecuteSends the transformed payload to the target system. The connector reconciles whether to create or update an existing record, based on a source-to-target ID mapping table.Target system rejects the payload (validation error, authentication failure, rate limit); target system unreachable.Check the target connection profile; inspect the run error message for the target system’s rejection reason; review field-length constraints in the mapping config.
FinalizeRecords the run outcome (success, partial success, or failure). Updates sync cursors for incremental sync so the next run starts where this one left off.Rarely fails on its own; a finalization failure may indicate a database connectivity issue in the integration service.Contact your system administrator if finalization consistently fails after Execute succeeds.

What happens when a stage fails

Section titled “What happens when a stage fails”
  1. The integration service retries the failed record automatically, up to a configurable maximum.
  2. If the record still fails after all retries, it is placed in the Dead Letter Queue (DLQ).
  3. The run is marked partial success (some records succeeded) or failed (no records succeeded).
  4. You can inspect the error message for each failed record in the run details view.
  5. Once the underlying problem is resolved, you can replay DLQ messages from the DLQ page, which re-injects them at the Ingest stage.

Partial success

Section titled “Partial success”

A run is marked partial success when at least one record succeeds and at least one record fails. The successfully processed records are written to the target; only the failed records appear in the DLQ. You do not need to re-run the entire job — replaying only the DLQ messages is sufficient.

Section titled “Related”