building-b2b — скилл для Claude Code: EDI-интеграции в Celigo

---
name: building-b2b
description: Build Celigo B2B Manager EDI integrations -- trading partner onboarding, EDI profiles, file definitions, X12/EDIFACT flow patterns, and transaction monitoring. Use when onboarding partners, editing EDI flows, setting up parsing rules or generating them from a specification PDF, or monitoring document exchange.
---

<!-- TIER:1 -->

# Building B2B / EDI Integrations

B2B Manager is Celigo's EDI hub for exchanging structured business documents with trading partners. It handles X12 (ANSI) and EDIFACT (UN) standards over FTP/SFTP, AS2, S3 and VAN connections, and over the folder (file) mode of cloud file providers such as Google Drive, Box, Dropbox, Azure Blob, Google Cloud Storage and Celigo Storage.

An EDI integration has these Celigo-specific components:

- **Trading partner connector** -- a pre-built template (590+) defining the connection type, EDI profile defaults, and export/import field requirements for a specific trading partner
- **EDI profile** -- interchange envelope settings (ISA/GS for X12, UNB for EDIFACT) that identify sender/receiver and control document versioning
- **File definition** -- parsing and generation rules that describe the segment/element structure of a specific EDI document type (e.g. one trading partner's 850 or 856)
- **Connection** -- FTP, AS2, S3, VAN or cloud file-provider credentials for the trading partner's EDI endpoint
- **Exports and imports** -- file-based data sources/destinations that use file definitions to parse inbound EDI or generate outbound EDI
- **Flows** -- pipelines wiring exports and imports together with transformations

## EDI Standards

**X12 (ANSI ASC X12)** -- North American standard. Documents are **transaction sets** identified by 3-digit codes (850 = PO, 810 = Invoice, 856 = ASN, 997 = FA, 855 = PO Ack, 846 = Inventory, 860 = PO Change). 50+ additional types supported including healthcare (834/835/837), transportation (204/210/214), and supply chain (753/843/861). Envelope: ISA → GS → ST → segments → SE → GE → IEA. Versions: 4010, 5010, 4030, etc.

**EDIFACT (UN/EDIFACT)** -- International standard. Documents are **messages** identified by 6-letter codes (ORDERS, INVOIC, DESADV, ORDRSP, RECADV, INVRPT, PRICAT, CONTRL). Additional messages: INSDES, OSTRPT, PARTIN, DELJIT, PRODAT, DELFOR, SLSRPT. Envelope: UNB → UNH → segments → UNT → UNZ. Versions: D93A, D96A, D01B, etc.

## Quick Reference

### Resource Decision Matrix

| Task | Resource | CLI command | Schema |
|---|---|---|---|
| Discover partner templates | Trading partner connector | `tp-connectors list` | [tp-connector-request.yml](references/schemas/tp-connector-request.yml) |
| Define interchange envelope | EDI profile | `edi-profiles create` | [edi-profile-request.yml](references/schemas/edi-profile-request.yml) |
| Define document parsing/generation | File definition | `file-definitions create` | [file-definition-request.yml](references/schemas/file-definition-request.yml) |
| Monitor document exchange | EDI transaction | `edi-transactions list` | [edi-transaction.yml](references/schemas/edi-transaction.yml) |
| Connect to partner endpoint | Connection (FTP, AS2, S3, VAN or a file provider) | `connections create` | See configuring-connections |

### Minimum Required Fields

| Resource | Required |
|---|---|
| EDI profile (X12) | To save: `name`, `fileType: "edix12"`. Before it parses or generates a file: `tpInterchangeId`, `myInterchangeId`, `tpIdQualifier`, `myIdQualifier`, `tpGroupId`, `myGroupId`, `isa01`–`isa04` (checked against every inbound file), `isa12` (version), `gs07`, `gs08`. Take the IDs from the partner's guide, a sample file or the connector; leave any nobody has supplied empty and ask -- never invent one |
| EDI profile (EDIFACT) | To save: `name`, `fileType: "edifact"`. Before use: `unb010_0001`, `unb010_0002`, `versionNumber`, `releaseNumber`, `controllingAgency` |
| File definition (X12/EDIFACT) | `name`, `version: "2"`, `format` (e.g. `delimited/x12`), `globalId` (X12/EDIFACT on EDI-licensed accounts), `delimited` block (`rowDelimiter`, `rowSuffix`, `colDelimiter`), `rules[]` (20 KB at most, serialized) |
| File definition (fixed-width) | `name`, `format: "fixed"`, `version: "1"`, `fixed.rowDelimiter`, `fixed.paddingChar`, and `rules[]` declaring every column of the line in order, each with a `length` -- including a placeholder element for positions you don't need (`startPosition` is ignored). A create or update missing `version`, `rowDelimiter` or `paddingChar` is refused with 422 |

### Schema Index

- [edi-profile-request.yml](references/schemas/edi-profile-request.yml) -- X12 ISA/GS and EDIFACT UNB fields
- [file-definition-request.yml](references/schemas/file-definition-request.yml) -- format, delimiters, rules structure
- [edi-transaction.yml](references/schemas/edi-transaction.yml) -- transaction query response shape
- [tp-connector-request.yml](references/schemas/tp-connector-request.yml) -- connector and supportedBy sections
- [tp-supported-by-section.yml](references/schemas/tp-supported-by-section.yml) -- connection, profile, export/import pre-configuration

## Related Skills

- [configuring-connections > Quick Reference](../configuring-connections/SKILL.md#quick-reference) -- FTP, AS2, and VAN connection types for trading partner endpoints
- [managing-file-storage > The Celigo-Hosted SFTP File Server](../managing-file-storage/references/file-server.md) -- partner SFTP accounts whose files land in Celigo Storage
- [configuring-exports > Quick Reference](../configuring-exports/SKILL.md#quick-reference) -- file-based exports that parse inbound EDI using file definitions
- [configuring-imports > Quick Reference](../configuring-imports/SKILL.md#quick-reference) -- file-based imports that generate outbound EDI using file definitions
- [building-flows > How to Build a Flow](../building-flows/SKILL.md#how-to-build-a-flow) -- wiring EDI exports and imports into flow pipelines
- [writing-scripts > Quick Reference](../writing-scripts/SKILL.md#quick-reference) -- preSavePage/postMap hooks for EDI record transformation and validation

<!-- TIER:2 -->

## How to Build an EDI Integration

### 1. Find the trading partner connector

Trading partner connectors are pre-built templates (590+) that define connection type, EDI profile defaults, and export/import config for a specific partner. A connector is a template you link to; no API call installs it. In the UI, trading partner onboarding builds the resources from it and prompts for the values the connector leaves to the user. Through the API or CLI you create each resource yourself (steps 3–6) and link the connection to the connector (step 3).

```bash
celigo tp-connectors list --distinct                                       # partner names (baseName)
celigo platform get 'v1/tpconnectors?baseName=<Partner>'                   # one partner's variants (exact match)
celigo tp-connectors list --fields _id,name,baseName,type,region,model     # every variant with its grouping fields
celigo tp-connectors get <connectorId>                                     # one variant, with supportedBy
```

The connector's `supportedBy` object tells you what's pre-configured and what the user must provide for the connection, EDI profile, and exports/imports. See [tp-supported-by-section.yml](references/schemas/tp-supported-by-section.yml) for the full structure. The list is a summary without `supportedBy`, so fetch the connector you need by id. Each connector is one transport, region and business model for a partner; a partner's variants share its `baseName`, and `celigo tp-connectors list --distinct` lists those partner names. List rows carry only `_id` and `name` unless you ask for more fields: `type` is the transport (`AS2` or `FTP`), `region` the partner's market, and `model` the business model (`none`, `Dropship`, `Warehouse`, `DVS`). The CLI list has no search flag; the API's `baseName` filter matches exactly, and returns nothing when no partner matches. No MCP tool reads the catalog. `create`, `update` and `delete` manage your own definitions, which stay unpublished and visible only to you unless Celigo has enabled the account to publish trading partner connectors.

If no connector fits, create the connection, EDI profile, exports and imports yourself, and still source the file definitions from a template or an existing definition (see [Sourcing EDI Resources](#sourcing-edi-resources)).

### 2. Check for existing resources

Before creating anything, check what the account already has. EDI profiles are per-partner (one profile covers all document types), so duplicates waste control number sequences. File definitions and EDI profiles are account-level -- no integration owns them -- so list them all rather than by integration, and choose a definition by partner, document type and direction.

When a partner already has a flow for another document, model the new export or import on it but don't copy everything: reuse its connection, its EDI profile and, inbound, its acknowledgement listener (`_postParseListenerId`), and take the file definition for the new document type -- another document type's definition won't parse it.

```bash
celigo account search "<partner-name>"
celigo edi-profiles list | grep -i "<partner-name>"
celigo file-definitions list | grep -i "<partner-name>"
celigo connections list | grep -i "<partner-name>"
```

### 3. Create the connection

Create the connection for the partner's transport: FTP/SFTP, AS2, S3, VAN, or a cloud file provider in folder mode. See [configuring-connections](../configuring-connections/SKILL.md) for full connection setup.

With a trading partner connector, link the connection to it: set `<transport>._tpConnectorId` on an `as2`, `ftp` or `s3` connection. The connector must be published (an unknown or unpublished id is rejected with 422 `tpconnector_not_found`), and VAN connections have no link field. Then set the fields the connector's `supportedBy.connection.fieldsUserMustSet` lists: the partner's real host and identity.

**Never copy the connector's pre-configured connection values onto the connection.** Apart from the transport type, they're template stand-ins, such as a placeholder AS2 partner ID and a staging AS2 URL. An AS2 connection's `partnerId` can't be changed once the connection exists -- an update with a different value is silently ignored -- so a copied placeholder is permanent, and fixing it takes a new connection. Get the partner's real AS2 ID before you create an AS2 connection.

```bash
celigo connections create --tp-connector <id or name> < connection.json   # sets <transport>._tpConnectorId, copies none of the stand-ins, and lists the fields left to set
celigo connections ping <connectionId>
```

### 4. Create the EDI profile

The EDI profile defines the interchange envelope -- ISA/GS segments (X12) or UNB segment (EDIFACT). Read [edi-profile-request.yml](references/schemas/edi-profile-request.yml) for all fields.

Key X12 fields: `tpInterchangeId`/`tpIdQualifier` (the partner's ID and its qualifier, e.g. ZZ = mutually defined) and `myInterchangeId`/`myIdQualifier` (yours). On files you receive the partner is the sender (ISA05/ISA06) and you the receiver (ISA07/ISA08); on files you generate it's the reverse. Also `isa01`–`isa04` (the parser checks the file's ISA01–ISA04 against them), `isa12` (version, e.g. 00401), `isa15` (P = production, T = test) and `controlNumber` (auto-incremented). Store interchange IDs unpadded (see gotcha 2). Celigo's definitions write `isa15` into ISA15 when generating and check an inbound file's ISA15 against it, so moving a partner from test to production is that one change, made when the partner switches; keep a separate test profile only when the partner's test system also uses different IDs. `isa15` is one of the fields an integration can ignore in pulls, so each environment can keep its own value.

With a trading partner connector, start from it: `edi-profiles create --tp-connector` fills the partner's envelope defaults (file type, X12 version, ISA/GS flags and qualifiers), never your own IDs, and lists on stderr the IDs left for you to supply. Check its `--dry-run` body first: some connector forms prescribe spaces for `isa02`/`isa04` or a padded partner ID, which inbound parsing rejects, so set those to `""` and the unpadded ID.

```bash
celigo edi-profiles create --tp-connector <id or name> --name "<Partner> X12" --dry-run   # inspect, then run without --dry-run
celigo edi-profiles create < profile.json
```

### 5. Create file definitions

Each document type (850, 810, 856, etc.) needs its own file definition with parsing/generation rules. Read [file-definition-request.yml](references/schemas/file-definition-request.yml) for the rules structure.

Key fields: `format` (`delimited/x12` or `delimited/edifact`), `globalId` (the standard document it implements; required on EDI-licensed accounts and immutable -- see [Sourcing EDI Resources](#sourcing-edi-resources)), `delimited.rowDelimiter` (what the parser splits segments on), `delimited.rowSuffix` (what generation appends after each segment, `~` for X12), `delimited.colDelimiter` (element separator, `*` for X12), `rules[]` (hierarchical segment/element tree). When each segment ends with `~` and a line break, set `rowDelimiter` to `~\n` (or `~\r\n`): a bare `~` leaves the line break on the next segment, and the parse fails at line 2 (`Required rule must have the respective row in the source file`).

A fixed-width definition (`format: "fixed"`) is read in element order: the parser ignores `startPosition` (and the legacy `start`/`end`), so a definition that skips a column misparses with no error. Declare every column of the line in order, including the ones you don't need: a run of positions you skip still takes a placeholder element of that width (it comes through as a field of its own). Give every element a `length` from 1 to 512. A save needs `version` (`"1"` on fixed-width definitions), `fixed.rowDelimiter` and `fixed.paddingChar`; without them it's refused with 422. Rows that carry no row-type marker need `ignoreIdentifier: true` on the row rule, inside a container (gotcha 18): without it they parse to one empty record, with no error. A one-time header line takes its own plain rule (not a container) with a marker element, ahead of the records container or wrapping it. `ignore: true` leaves an element out of the record while keeping its width.

A line break after the last row is read as one more, empty row. With a required row rule the parse fails at that line (`Required rule must have the respective row in the source file. ... for line: <n>`); otherwise the last record comes back as `{}`. Set `skipIntermittentEmptyLines: true` on the definition to drop empty lines, including that one.

File definitions have no page of their own in the integrator.io UI: people create and edit them from an export's or import's file settings. Cloning an export or import that uses one (or a flow or integration that contains it) creates a copy of the definition, with the same name, for the clone: from then on the copies change independently, and two definitions share one name, so tell them apart by `_id`.

Before linking a definition to a step, test it with the profile attached: parse the partner's sample, or generate from sample records and treat empty output as a failure. Without a profile the parser skips the envelope check, so a profile mismatch would only surface in the run. An envelope, profile or standard violation fails the whole call with a 422 that names the segment, element and value (see [Common Errors](#common-errors)); check `recordLevelErrors` on a 200 as well.

```bash
celigo file-definitions create < filedef.json
celigo processors parse edi sample.edi --file-definition-id <id> --edi-profile-id <profileId>   # or --file-definition <filedef.json>; also parses fixed-width
celigo processors generate edi records.json --file-definition <rules.json> --edi-profile-id <profileId> --jq .data
```

### 6. Create exports and imports

EDI runs on any file transport that carries an EDI profile: FTP/SFTP, AS2, S3, and the folder (file) mode of cloud file providers (Google Drive, Box, Dropbox, Azure Blob, Google Cloud Storage and Celigo Storage, with `http.type: "file"`). VAN connections exchange EDI too. Use `FTPExport`/`FTPImport` (with `ftp.directoryPath`), `AS2Export`/`AS2Import` (the transport settings live on the AS2 connection, so there's no directory path), `S3Export`/`S3Import`, or `HTTPExport`/`HTTPImport` in file mode. A records-mode HTTP step can't take a profile: the save is refused with `not_supported`.

**Inbound EDI export:** `file.type: "filedefinition"`, `file.fileDefinition._fileDefinitionId` and `_ediProfileId`, on one of the adaptors above.

**Outbound EDI import:** the same file definition and profile references, plus how a run's records become files: `file.aggregation.type: "page"` with `file.skipAggregation: true` (one file per page), or `"key"` with `false` (one file per document key; B2B Manager accounts only). The key comes from the file definition's document type, so there's no key field to set. `"all"` isn't allowed for EDI, and a `page` import saved without `skipAggregation: true` fails with 422 `not_supported` ("Aggregation is not supported for EDI files, please set skipAggregation to true in Imports").

See [configuring-exports](../configuring-exports/SKILL.md) and [configuring-imports](../configuring-imports/SKILL.md) for full field schemas.

### 7. Wire into flows

Typical patterns:

- **Inbound:** FTP export (parse EDI) → transform EDI fields to ERP → ERP import
- **Outbound:** ERP export → transform to EDI → FTP import (generate EDI)
- **997 FA:** a separate acknowledgement flow (a listener source, then an import that generates the 997), which the inbound export calls through `_postParseListenerId` -- see [Functional Acknowledgements](#functional-acknowledgements-997--contrl)

See [building-flows](../building-flows/SKILL.md) for scheduling, chaining, and error management.

## Document Grammar vs Partner Identity

The most important conceptual split in Celigo's EDI model:

- The **file definition** owns the *document grammar* -- the segments, elements, loops, and envelope structure of one document type (850, 810, ORDERS), one per document type **and direction**.
- The **EDI profile** owns the *partner identity* -- the interchange IDs, qualifiers, group IDs, version, and control settings that fill that envelope. One profile per trading partner, per EDI standard, no matter how many document types you exchange.

The two meet at runtime. Envelope elements in a file definition's rules don't hardcode identity values -- they carry `{{{ediProfile.…}}}` references, and the platform substitutes the values from the profile linked on the export/import (`_ediProfileId`). On **parse** (inbound), the substituted values are validated against the actual file bytes -- a mismatch fails the document with an EDI-profile validation error (an identity problem, not a grammar problem). On **generate** (outbound), the values are written into the envelope of the file being produced.

A file-based EDI step therefore needs **both** resources: the platform rejects an X12/EDIFACT file definition that has no linked profile. Sequence the profile before the exports/imports that reference it, exactly as you would a connection.

When you write a binding yourself, use only keys the profile has. For X12 those are `tpInterchangeId`, `myInterchangeId`, `tpIdQualifier`, `myIdQualifier`, `tpGroupId`, `myGroupId`, `isa01`–`isa04`, `isa11`, `isa12`, `isa14`–`isa16`, `gs07`, `gs08` and `controlNumber`; the EDIFACT keys are in [rules.yml](references/filedefinition-schemas/rules.yml). There are no `isa05`–`isa08` keys: the qualifier and ID positions bind to the `tp*` or `my*` pair, by direction. Leave the date, time and control bindings a Celigo template ships with as they are. An unknown key saves, then fails the parse, and generation returns an empty file without an error, so test every definition before linking it (step 5).

### One Profile, Both Directions

A profile is direction-agnostic. Its fields are labeled by *whose* identity they hold (`tp*` vs `my*`), not by sender/receiver position. On an inbound parse the partner is the sender, so the file definition's rules bind the sender slots to the `tp*` values and the receiver slots to `my*`; on an outbound generate the orientation flips (sender → `my*`, receiver → `tp*`). One partner profile serves the 850s coming in and the 810s going out. This is a notable asymmetry with file definitions, which come in **separate parse and generate variants** per document type -- parse rules tolerate what partners send, generate rules must produce exactly what partners require.

## Sourcing EDI Resources

### Building an EDI Profile from a Sample File

The fastest correct path to a new profile is **not** hand-copying values out of a companion guide -- it's reading a real file from the partner. No public API route, CLI command or MCP tool extracts a profile from a file, so read the envelope yourself. On an X12 file the partner sent you:

| File | Profile field |
|---|---|
| ISA01–ISA04 | `isa01`–`isa04` (a blank ISA02/ISA04 becomes `""`) |
| ISA05 / ISA06 | `tpIdQualifier` / `tpInterchangeId`, trimmed |
| ISA07 / ISA08 | `myIdQualifier` / `myInterchangeId`, trimmed |
| ISA11, ISA12, ISA14–ISA16 | `isa11`, `isa12`, `isa14`–`isa16` |
| GS02 / GS03, GS07 / GS08 | `tpGroupId` / `myGroupId`, `gs07` / `gs08` |

Then parse the sample with the new profile attached (step 5): an envelope value that doesn't match fails with a 422 naming it.

- Review the values before creating -- especially the usage indicator (`isa15`, `T` vs `P`) and the qualifiers -- since they reflect that one file.
- Name the profile after the partner (e.g. "Acme Corp X12").
- A file the partner *sent you* has the partner in the sender slots. When it's ambiguous, confirm which direction the sample flows -- what you receive vs what you must produce.

### Never Start EDI from Scratch -- Begin from a Template

Celigo ships a global catalog of pre-built EDI templates -- X12 and EDIFACT document definitions, many vendor-specific (per-retailer 850 variants and the like), each tagged with vendor, document type, and direction. Templates are instantiated **into** account-level file definitions, which you then customize to the partner's companion guide. The catalog is browsable only in the UI; an API token can't list it. Canonical sourcing order:

1. An account-level file definition of the **same document type** already exists → reuse it or use it as the base.
2. A global template matches → have the user add it in the UI, then customize the definition it creates.
3. No template fits, but the partner has a specification PDF → generate rules from it ([Generating a File Definition from a Specification PDF](#generating-a-file-definition-from-a-specification-pdf)).
4. Build from scratch → last resort, for documents no template covers.

On EDI-licensed accounts an X12 or EDIFACT file definition needs a `globalId` from Celigo's standard-document registry: a create without one fails with `global_id_not_provided`, an invented one with `invalid_global_id`, and it can't be changed later. With an API token, reuse the `globalId` of an existing definition for the same document type, or ask the user to add the template in the UI.

**Same-type rule:** a file definition is only a valid base for the *same transaction set type*. An existing 850 is a fine starting point for another partner's 850; an 860 is **not** a starting point for an 850 -- different documents, different segment structures. Hand-building a rules tree when a template exists invites subtle mistakes in envelope close rules and element conventions.

For onboarding a **whole partner** (not just one document), start from the partner's trading partner connector (see step 1). It provisions nothing by itself: in the UI, trading partner onboarding builds the resources from it and prompts for what it leaves to the user; through the API or CLI you create the connection, EDI profile, exports and imports yourself and link the connection to the connector (step 3). Build individual EDI steps directly only when adding one document flow against an already-onboarded partner.

### Generating a File Definition from a Specification PDF

`celigo file-definition-rules` sends a partner's specification PDF (X12 or EDIFACT) to an AI rule generator and returns file definition rules as JSON; it saves nothing. The REST routes are under `/v1/filedefinitionrules`, and no MCP tool runs it.

1. **Check the document type first.** `celigo file-definition-rules document-types` lists the X12 transaction sets the generator supports (850, 810, 856, 940 and others) and whether EDIFACT is (`--document-type 0` detects an EDIFACT specification). `generate` and `parse` refuse a type that list doesn't include before submitting, at no cost; called directly, the API refuses it with 400 `INVALID_DOCUMENT_TYPE`, and a submission the service refuses still counts. Each user may submit 10 `generate` and 10 `parse` jobs an hour (the account owner and administrators aren't limited).
2. **Submit once, with `generate`.** `generate` returns both artifacts for one submission; `parse` returns only the parsing rules. The CLI waits for the job (up to `--timeout`, 420 seconds by default); with `--no-wait` it prints a `requestId` that `celigo file-definition-rules status <requestId> --wait` (`--type parse` for a parse job) picks up within 24 hours. The PDF must carry text: a scanned or image-only one is accepted, and its job fails with `DETECTION_FAILED`. A guide for a different transaction set than `--document-type` fails with `INVALID_DOCUMENT_TYPE`, and a PDF over 50 MB encoded is refused with 413.
3. **Create from the right artifact.** `generationFdr` is a complete file definition body; `parsingFdr` is `{resourcePath, fileDefinition}` for embedding in an export or import, so take `.parsingFdr.fileDefinition` to create it on its own. Add a `globalId` copied from an existing definition of the same document (without one the create fails with `global_id_not_provided`), then create it and test it like any definition: parse the partner's sample with the profile attached ([step 5](#5-create-file-definitions)). With no sample at hand, say the definition is untested and ask for one.

```bash
celigo file-definition-rules document-types
celigo file-definition-rules generate <guide.pdf> --document-type 850 --jq .generationFdr > filedef.json   # add globalId, then:
celigo file-definitions create < filedef.json
```

## Functional Acknowledgements (997 / CONTRL)

Functional acknowledgements -- `997` (X12) and `CONTRL` (EDIFACT) -- are how EDI parties confirm receipt of an interchange. They are **ordinary file definitions** with the `documentType` field set (`997` or `CONTRL`), not a separate resource type. Accounts exchanging EDI typically wire them in **both directions**: generate an acknowledgement for every interchange you receive, and parse the acknowledgements your partner returns for the documents you send.

The generate side is a **separate acknowledgement flow** in the same integration. Its source is a listener -- an export with `type: "webhook"` and `webhook.provider: "integrator-extension"` -- and its import generates the acknowledgement with a file definition whose `documentType` is `997` (or `CONTRL`) and sends it to the partner. Point the inbound EDI export's `_postParseListenerId` at that listener (the UI's **Send functional acknowledgment** option): the platform calls it once per parsed file, on success and on failure, with any parse errors in the payload. `_postParseListenerId` is accepted only on FTP, AS2, S3, and HTTP file-mode exports, and any other kind of listener is rejected with `invalid_post_parse_listener`. There is no `file.faAcknowledgement` setting. Track acknowledgement state per document via `faStatus` (see Monitoring EDI Transactions).

## Strict Validation and the Skip Flags

EDI parsing checks inbound files against the linked profile by default, and against the EDI standard's element rules only when a definition asks for it. Two file-definition flags control that:

- `skipEDIProfileValidation` -- skip checking the envelope against the linked EDI profile. Defaults to `false`, so profile checks run.
- `skipEDIValidation` -- skip element validation: lengths, data types, code lists, mandatory elements and element relationships. **Omitted means skipped**: element checks run only on a definition that sets `skipEDIValidation: false`. A missing mandatory segment fails the parse either way.

Turn element validation on deliberately when you want partner errors caught at parse, and parse recent files from every partner that uses the definition before saving that change -- it changes which files the definition accepts. Skipping profile validation is an escape hatch: prefer fixing the profile, and reach for it only when a partner's non-conformance is confirmed, acknowledged, and not going to be fixed on their side.

**When one transaction set is bad.** By default one failed transaction set (ST–SE, UNH–UNT) fails the whole file. With `allowPartialSuccess: true` in the export's file-definition settings (`file.fileDefinition.allowPartialSuccess`) and the EDI profile linked, the failed set is set aside and reported as an error, the file's other sets go on as records, and that functional group's acknowledgement status is partial (`P` on X12).

## Monitoring EDI Transactions

The full reference -- every query rule, acknowledgements and AS2 receipts, the files behind a record, the CSV export, retention, and the CLI and MCP call for each -- is [references/monitoring.md](references/monitoring.md).

B2B Manager tracks every EDI document processed. Key transaction fields: `documentType`, `documentNumber`, `direction` (Inbound/Outb...