Content conversion parameters, explained one by one

These are the file adapter settings that drive content conversion. The names below are the parameter names as they appear in the channel; the behaviour is what matters, and it is the same whether you are configuring a sender or a receiver channel — only the direction of the transformation flips.

Document identity

Document Name and Document Namespace

These tell the adapter what to call the XML document it produces. The document name corresponds to the message type in the Integration Repository, and the namespace is attached to it. Mapping only resolves against the right message type if these two are correct, so a mismatch here fails later, in the mapping, with a message that does not mention the channel.

Document Offset

The number of lines to skip at the beginning of the file. This is how you discard comment lines, banner text or a column header row that is not part of the data. Defaults to zero when left empty.

If a receiver reports that the first record contains your header labels, this is the parameter that was left at zero.

Recordset name and structure

Recordset Name

The root node the adapter wraps everything in. It defaults to Recordset. If the receiving mapping expects no wrapper at all, this is the setting to suppress — either by naming it to match the expected root or by configuring the adapter to ignore it.

Recordset Structure

The shape of the document, written as a comma-separated list alternating node name and cardinality:

• Data,* — a node called Data that repeats without limit. The common case.
• Header,1,Item,* — exactly one Header, then unlimited Item nodes.
• H1,*,D1,* — two repeating node types, which requires a key field.

The node names you choose here become the XML element names. They are not derived from the file — the file has no opinion about them — so they must match what the mapping downstream expects. This is the single most common place to create work for yourself later.

Recordsets per Message

How many recordsets are packed into one message, defaulting to unlimited. When a file exceeds the configured count, the adapter splits it into multiple messages instead of one large one. Useful when a huge file would otherwise blow up mapping memory.

Recordset Sequence

Two values, and the difference matters more than it looks:

• Ascending — the adapter assumes the recordset structure appears in the order you declared it, and treats the reappearance of an earlier node as the start of a new recordset.
• Variable — the order is not fixed. If every structure is declared as variable, the whole document is interpreted as a single recordset.

Choosing Ascending for a file whose record types are interleaved produces records that look shuffled — data appearing under the wrong node, or records merging. When the output shape is recognisably data but organised wrongly, check this parameter before anything else.

Separators

<Node>.fieldSeparator

The delimiter that splits a record into fields. A comma for CSV, a semicolon where the data itself contains commas, \t for tab-delimited.

<Node>.endSeparator

What marks the end of a record, almost always the newline. This is the one parameter where the literal nl is accepted.

Escape sequences

Both separator parameters accept escape sequences and hexadecimal character codes:

• \t — tab
• \n — line feed
• \r — carriage return
• \x<code> — an arbitrary character, given as its hexadecimal code

Files written on Windows and files written on Unix are not the same file, even when they look identical in an editor. A file ending its lines with \r\n will not parse correctly against an end separator of \n alone — the carriage return stays attached to the last field, which is how you get a final column that looks correct but never matches anything in a lookup.

Fixed-length fields

<Node>.fieldFixedLengths

An alternative to a field separator: a comma-separated list of field lengths, splitting the record by position. The count of lengths must equal the count of fields — a mismatch is a configuration error, not something the adapter recovers from.

Fixed-length files are common from mainframe and older ERP sources, and they are brittle in a specific way: a single field that overflows its declared width shifts every field after it, so one bad record can produce a whole row of plausible-looking wrong values.

<Node>.keepIncompleteFields

Only meaningful alongside fixed lengths. It decides what happens when the final field in a record is shorter than declared — transfer it as-is, or fail the conversion. Choose deliberately; the default is not always what a legacy receiver expects.

<Node>.fieldNames

An ordered, comma-separated list of field names for the node. Where the source file has no header row, this is how the XML elements get meaningful names rather than generic ones.

<Node>.processFieldNames

Set to fromConfiguration when the flat file carries no header row of its own and the names must come entirely from your configuration rather than from the data.

Quoting and enclosures

Real CSV is not just commas. A field containing a comma is quoted, and a quoted field containing a quote escapes it. Three parameters handle this:

• enclosureSign — the character that opens a quoted field, usually ".
• enclosureSignEnd — the closing character, where it differs from the opening one.
• enclosureSignEscape — how an enclosure character inside a quoted field is escaped.

Leave these unset and a file containing "Smith, John" splits into two fields instead of one — and every subsequent field in that record shifts by one position. The record still parses, which is what makes it hard to spot.

Key fields

Key Field Name and Key Field Type

When a file mixes record types — a header line, then detail lines, then a trailer — the adapter needs to know which is which. A key field is a field present in every substructure whose value identifies the type.

<Node>.keyFieldValue

The constant that marks a given substructure. A header node might declare a key field value of V00; a line whose key field holds that value is parsed as a header rather than as data.

<Node>.keyFieldInStructure

Whether the key field itself appears in the generated XML. Values are ignore to leave it out and add to include it. Including it is usually the right call during development and often the wrong one in production, because the receiver rarely expects a field that exists only to help the parser.

A key field becomes mandatory once any node in the Recordset Structure has unlimited cardinality. Omitting it is one of the failures covered in the error guide.

Gotchas worth memorising

• nl works only in endSeparator. Everywhere else use \n.
• \n works everywhere, including in endSeparator — so if you are unsure, it is the safer choice.
• Line endings from Windows files leave a trailing \r on the last field of every record.
• Mismatched fieldFixedLengths counts fail the conversion outright rather than degrading.
• Node names in the Recordset Structure become element names. They are a contract with the mapping, not a description of the file.

To see these applied to a concrete file, work through CSV to XML, or go back to the content conversion overview.