Gateway Routes and Handlers

Gateway Routes and Handlers

A route answers "a file landed at this path — what should run?". It is the one abstraction the gateway adds, and what it buys is that the same hardened endpoint serves EDI, script triggers, OCR intake and data loads without any of them knowing about the others.

Routes tab. Managing them needs DataMagik - Builder.

Folder patterns

The vocabulary is deliberately small, because an operator has to be able to predict it:

/inbound/edi/**            every file anywhere under /inbound/edi
/inbound/edi/acme/**       only that partner's folder
/inbound/*/orders          "orders" one level down
/inbound/invoices/*.pdf    PDFs directly in that folder
/inbound/edi               the folder itself — also claims everything inside it

Which route wins

Every enabled route that matches is considered, then ordered — most deliberate configuration first:

1. A route written for this principal beats a company-wide default.
2. A higher explicit priority — your own override.
3. The longer literal prefix: /inbound/edi/acme/** beats /inbound/**.
4. Fewer wildcards — less guessing.
5. A deeper pattern.
6. Finally the oldest route, so identical patterns always resolve the same way.

In the screenshot, /inbound/invoice/** at priority 20 wins over the priority-10 /inbound/script/** where both could match.

When nothing matches

The file is still stored and recorded as unrouted. Losing a partner's file because nobody wrote a rule yet is not an acceptable outcome. Add the route, then replay — replay re-resolves the route, so the fix takes effect.

The handlers

Store only

No configuration. The bytes are durably stored and the transfer is marked processed. A legitimate integration when a script or a person collects the file later.

EDI

No configuration. The file goes through the full inbound EDI pipeline — parsed, matched to a trading partner by its ISA sender, mapped, validated, routed, recorded and acknowledged. The transactions it produced are linked back to the transfer.

Script

One field: the script name. See The Script Handler for what the script receives and how its return value decides the transfer.

OCR extraction

The extraction profile to read the document with, and optionally a script to hand the extracted fields to. See The OCR Handler.

Load into a lookup table

The lookup table to import into and the key column — the header in the delivered file that identifies each row. Left blank, the table's own key column name is used.

Format is taken from the route if set, then the file extension, then sniffed. A partner's filename is not a contract, and refusing good JSON because it was called .txt would be pedantry. CSV needs a header row; JSON may be an array of objects, an object wrapping one under rows/data/items/records, or a single object.

Rows are upserted, because a partner sending a full snapshot every week means "this is the current set", not "add these again".

Configuration is validated when you save

An OCR route with no profile, or a lookup route with no table, is refused in the console — using the same rules the handler will later apply. Two different notions of "is this configured?" is how a route saves cleanly and then fails at 3am when a partner's file lands.

A worked setup

/inbound/edi/**        → EDI                      (purchase orders and releases)
/inbound/invoices/**   → OCR "AP invoice" + script postApInvoice
/inbound/pricelist/**  → Load into lookup "supplier-prices", key column "sku"
/inbound/**            → Store only               (catch-all, so nothing is unrouted)

The catch-all is worth adding once you are past setup: it turns "unrouted" from a normal event into a signal that a partner is writing somewhere unexpected.