Map Integrations and Data Flows with Every Unknown Marked OPEN

Workflow area: Solution Evaluation · Tier: Core · Hands-on time: ~35 minutes

Integration mapping is detail work with brutal failure economics: one wrong field mapping — currency assumed from the wrong system, an ID matched on the wrong key — surfaces months later as corrupted records and a reconciliation project. LLMs are genuinely good at reading OpenAPI specs and drafting mappings, but they are equally good at inventing a plausible field correspondence where none exists. The discipline is structural: the model may draft, it may never resolve an unknown, and nothing ships until a named data owner has initialed the rows they own.

When to use — and when not to

• Use it when scoping integrations for a new solutionthe interface catalog and flow diagram are the artifacts the architecture review and the vendor SOW both need.
• Use it to draft field mappings from source and target specsAPI docs, data dictionaries, CSV layouts — where the clerical bulk is exactly what AI removes.
• Use it to document undocumented as-is flowsfeeding it config exports, middleware logs, and tribal-knowledge notes produces a draft the integration team can correct, which beats a blank page by weeks.
• Skip it as a substitute for the data owner conversationa mapping validated by nobody is a guess with a table around it, whoever drafted it.
• Skip transformation-logic design in prosebusiness rules for transformation (rounding, deduplication, precedence) are requirements to elicit, not correspondences to infer.
• Skip it when specs are unavailable rather than unreadif there is no documentation and no owner to interview, the honest artifact is a discovery plan, not a diagram.

The recipe

1. 1.

   Inventory the endpoints and their paperwork. List systems in scope, and for each collect what exists: API specs, data dictionaries, extract layouts, middleware configs, and the name of the data owner or system SME. Where documentation is missing, record that as the first OPEN item — do not let the gap silently vanish into a smooth diagram.

2. 2.

   Draft the interface catalog and flow diagram. Attach specs and inventory:

   Copy

   You are drafting integration documentation for a business
   analyst. Systems and docs attached. Scope: [ONE LINE].
   
   Produce:
   1. INTERFACE CATALOG — one row per interface: ID | source |
      target | trigger (event/schedule/manual) | mechanism
      (API/file/queue/manual) | frequency | payload summary |
      volume if stated | evidence (doc + section) | owner.
   2. DATA-FLOW DIAGRAM as Mermaid: systems as nodes,
      interfaces as labeled arrows with IF-IDs.
   
   Rules: every catalog cell is either backed by a citable doc
   statement or contains exactly "OPEN: <what is unknown>".
   Never infer frequency, volume, or mechanism from typical
   practice. If two docs disagree, create an OPEN item quoting
   both. List all OPEN items in a numbered register at the end.
   

3. 3.

   Generate field mappings per interface — with the same contract. For each interface that carries structured data:

   Copy

   Map source [SYSTEM/ENTITY, spec attached] to target
   [SYSTEM/ENTITY, spec attached].
   
   Output rows: source field (name, type, constraints) | target
   field | transformation (VERBATIM-COPY / CONVERT: <rule> /
   DERIVE: <rule> / CONSTANT / OPEN) | nullability conflict? |
   confidence HIGH/MEDIUM/LOW | validation question for the
   data owner.
   
   Rules: matching names are evidence, not proof — flag
   same-name-different-meaning risks (e.g. "status", "type",
   "date"). Any field without a confident counterpart maps to
   OPEN, never to the closest plausible field. List target
   mandatory fields with no source, and source fields with no
   target, in separate residue tables.
   

   Sample of output doing its job:

   Copy

   vendor.currency | supplier.currency_code | OPEN: source doc
   does not state if currency is order-level or vendor-default
   | — | LOW | "Which currency does field 12 actually carry?"
   vendor.tax_id | supplier.vat_no | OPEN: formats differ
   (free text vs validated VAT); transformation rule needed |
   nullability conflict: target mandatory, source 9.4% null |
   MEDIUM | "What populates vat_no when tax_id is null?"
   

4. 4.

   Route rows to owners, not to a meeting. Split the mapping by owning system and send each data owner their rows plus the validation questions, asking for one of three responses per row: CONFIRMED, CORRECTED (with the fix), or ESCALATE. The per-row question format gets answers a "please review the mapping doc" email never will. Record who confirmed what, and when.

5. 5.

   Burn down the OPEN register visibly. The register — not the diagram — is the project's real status. Each OPEN item gets an owner and a resolution path (doc request, SME interview, test transaction). An integration workshop agenda is simply the register sorted by owner. Items resolve by evidence, and the resolution is written into the catalog with its source.

6. 6.

   Version and hand off. The deliverable set: interface catalog, rendered flow diagram, per-interface field mappings with confirmation records, residue tables (unmapped mandatory fields are requirements, not footnotes), and the OPEN register with its burn-down state. Date it and state the spec versions used — integrations drift, and the header is what tells the next analyst whether this map is history or current.

Make it yours

• Claude over API specs for the drafting pass: attach whole OpenAPI/WSDL files; section-level citations in the catalog make owner validation dramatically faster.
• Mermaid or Lucid for the diagram layer: keep Mermaid source in the repo so diagram updates are diffs; regenerate the picture, never hand-edit it out of sync with the catalog.
• Spreadsheet mappings as the validation vehicle: owners live in Excel — export mappings with a CONFIRMED/CORRECTED/ESCALATE column and conditional formatting on OPEN and LOW-confidence rows.
• Middleware-config mode for as-is discovery: feed MuleSoft/Boomi/SSIS export files to the AI to reverse-draft the catalog of what actually runs today, then reconcile against what anyone believed was running — the deltas are findings.

Quality check

• No invented correspondencesevery non-OPEN mapping cell cites spec evidence; spot-check the LOW and MEDIUM confidence rows against the source documents yourself.
• OPEN items are enumerated, owned, and datedthe register exists, has an owner per item, and its count is trending down with evidence-backed resolutions.
• Every row has a named validatorCONFIRMED/CORRECTED responses are on record per data owner; unvalidated sections are labeled as such, not blended in.
• Residue tables were promotedtarget-mandatory fields with no source became requirements or explicit decisions, not silence.
• Same-name traps were hunted"status", "type", "date", "amount" fields carry an explicit semantic check, not a name match.
• The artifact is versionedspec versions, confirmation dates, and OPEN count in the header.