The X12 format parses and emits X12 EDI messages (850 purchase orders, 810 invoices, 856 ASNs, 837 claims, 835 remittances, …). It is the dedicated X12 connector in Etlworks — tuned for X12, supports much larger files than the generic EDI format (~100 MB vs ~100 KB), and supports both read and write. This article is the parameter reference. For the end-to-end usage walkthrough — flow patterns, transports (AS2, SFTP, HTTP), mapping, acknowledgments — see Working with X12.
When should I use this format?
Use the X12 format for any X12 EDI exchange. For other EDI dialects, use a different format:
The X12 format is included in all editions of Etlworks. The generic EDI format can also parse X12, but the dedicated X12 format is the recommended choice for X12 work — faster, handles larger files, supports writing.
Main usage patterns
The X12 format powers three patterns documented end-to-end in Working with X12:
| Pattern | How |
|---|
| Read X12 at scale (direct EDI to file, no mapping) | X12 format as the source; EDI to file flow type emits XML / JSON / CSV directly. Fastest path, lowest CPU and memory footprint. Use for high-volume conversion. See Read X12 at scale. |
| Read X12 with visual mapping | X12 format as the source in a regular ETL flow; nested mapping shapes the output. Use when transformation is needed. See Read X12 with visual mapping. |
| Generate X12 from any source | X12 format as the destination; the X12 Message Designer (primary) or nested mapping (secondary) populates segments. See Generate X12 from any source. |
Create an X12 format
- Open Connections and select the Formats tab.
- Click +, search for X12, and select X12 (in the EDI group).
- Set EDI Version and Transaction Set (the two most important settings) and any other parameters you need.
EDI document
| Parameter | Default | What it does |
|---|
| EDI Version | 00401 | X12 release. 004010, 005010, and 006010 are the most common in production; most earlier versions are also supported. The default schema (00401) is bundled with Etlworks; other versions download from the Etlworks EDI schema bucket on first use. |
| Transaction Set | (blank) | The X12 transaction set: 850 (purchase order), 810 (invoice), 856 (ASN), 837 (healthcare claim), 835 (healthcare remittance), 277 (claim status), 204 (motor carrier shipment), and so on. Required for write; useful on read to anchor the parser to a known transaction. |
| EDI schema Filename or Path | (blank, auto) | Override the default schema location. The default for X12 is RSSBus_00401.json; the schemas assign human-readable names to EDI elements and segments. Override only when running offline or pinning to a specific schema patch. |
| Cache X12 Metadata | true | Cache the parsed X12 schema metadata for this format instance. Disable only when the schema file can change while the flow is running — rare. |
EDI to XML, JSON, or CSV
Settings that control the rapid-conversion path (no mapping). For the end-to-end walkthrough see Read X12 at scale: direct conversion in Working with X12.
| Parameter | Default | What it does |
|---|
| Output File Name for Converted EDI Document | (blank) | Path to the output file. Sets the destination of the rapid conversion. Wildcards (out/*.csv) work to emit one output file per input X12 file. |
| Skip Parsing EDI Document | false | Skips detailed parsing and emits the output file without going through the standard parser. Faster but produces less normalized output. Useful for extreme-volume direct conversion. |
| Parse XML Attributes | true | Preserve type attributes (Segment, Loop, etc.) in the converted output. Disable for a flatter shape without the type metadata. |
CSV output options
When the destination format is CSV, the X12 connector emits one CSV file per segment type, per loop, per Transaction Set, per Functional Group, and per Interchange. These options tune what gets emitted. For the structure description see Conversion to CSV: structure in Working with X12.
| Parameter | Default | What it does |
|---|
| Include Interchange Record | true | Include the Interchange (ISA / IEA) CSV file in the output. Disable to skip the Interchange-level record. |
| Include Functional Group Record | true | Include the Functional Group (GS / GE) CSV file. Disable to skip GS-level records. |
| Segments to Exclude | (blank) | Comma-separated list of segment names to exclude from CSV generation (case-sensitive). Useful when downstream systems don't need certain segments — e.g., exclude NTE when you only want the transactional segments. |
| Include Segment Name in CSV Filename | false | Prepend the segment name to CSV filenames for clarity, e.g., N1_Party_Identification.csv instead of Party_Identification.csv. |
Validation
| Parameter | Default | What it does |
|---|
| Strict schema validation | no | Enforce the X12 schema strictly during parse. Off by default; many production partners send messages that pass real-world validators but fail strict checks — enable only when you know your partner is compliant. |
| Enable cross-field validation rules | no | Run cross-field validation defined in the schema (e.g., conditional requirements where field B is required when field A has a specific value). |
Parser fine-tuning
The parser auto-detects delimiters and message structure from the ISA envelope in most cases. Override these only when a partner uses non-standard delimiters that aren't declared correctly in the envelope.
| Parameter | Default | What it does |
|---|
| Use long element names | yes | Use human-readable element / segment names in the output (e.g., OrderingProvider) instead of short codes (e.g., NM1). Recommended for readability of mapped output. |
| Include Empty Elements | yes | Include empty data elements inside composite elements. Disable to produce a more compact output. |
| Include Footers | yes | Include footer information (IEA, GE, SE counts) in the XML output. |
| Component delimiter | (blank, auto) | Override the component-element separator. Default is detected from ISA-16. |
| Element delimiter | (blank, auto) | Override the data-element separator. Default is detected from ISA element 0. |
| Segment delimiter | (blank, auto) | Override the segment separator. Default is detected from the byte after ISA-16. |
| Release character | (blank) | Character used to escape delimiters within values. |
| Repetition character | (blank, auto) | Override the repetition character. Default is detected from ISA-11. |
| Parameter | Default | What it does |
|---|
| Preprocessor | (blank) | JavaScript that modifies the raw X12 message before the parser sees it. See Preprocessor. Useful for fixing partner-specific quirks that aren't worth a full transformation step. |
| Default Extension | x12 | File extension assumed when the source filename has none. |
| Column names compatible with SQL | true | Replace characters that aren't alphanumeric or spaces in column names. Helps when loading parsed X12 directly into a relational database. |
| All fields are strings (required) | false | Create all fields with a string data type instead of inferring numeric / date types. Useful when downstream targets are agnostic and you want to preserve the raw text. |
| Date and Time Format | MM/dd/yyyy HH:mm:ss | Format for date+time output (Java SimpleDateFormat pattern). |
| Date Format | MM/dd/yyyy | Format for date-only output. |
| Time Format | HH:mm:ss | Format for time-only output. |
| Parse Dates | off | When the input doesn't match the configured formats, attempt automatic parsing. |
| Trim Strings | off | Strip leading / trailing whitespace from string values. |
| Convert 'null' to null when reading | off | Treat the literal string 'null' (case-sensitive) as a SQL null. |
| Convert empty string to null when reading | false | Treat empty strings as nulls. |
| Value for null when reading | (blank) | Comma-separated list of tokens (e.g., NULL, n/a, -) interpreted as null. |
| Convert boolean true / false to numeric 1 / 0 | false | Coerce boolean values to numeric when writing. |
| Encoding | UTF-8 | Character encoding for the input. |
| Template | (blank) | When the actual input file isn't available during flow design, the template populates column names so mapping can still be built. |
Overrides
| Parameter | What it does |
|---|
| Function to calculate Filename | JavaScript that rewrites the file name when reading or creating an X12 file. The input is fileName; assign the result to value. Useful for dropping prefixes, appending dates, normalizing partner-specific naming conventions. |
| Function to calculate Field Name | JavaScript that rewrites column names produced by the parser. The input is name; assign the result to value. |
The X12 format handles files up to ~100 MB — orders of magnitude more than the generic EDI format's ~100 KB sweet spot. For high-volume scenarios:
- Use the direct conversion path (EDI to file, no mapping) — fastest, lowest CPU and memory footprint.
- Process many files in parallel via Use Parallel Threads when processing sources by a wildcard (under Flow > Configure > Parameters).
- For partner-side batching of small messages into large interchanges, use the X12 format's native parser rather than splitting upstream.