File Content Conversion migration

PI file sender channels with Flat→XML and file receiver channels with XML→Flat File Content Conversion (FCC) are migrated together with their conversion settings. This page describes how the conversion is reproduced in the migrated IFlow, which channel parameters are carried over and where the result can differ from PI.

1. Conversion modes

The File Content Conversion Mode setting of the migration configuration (shown only if at least one channel uses File Content Conversion) defines how the conversion is reproduced:

  • Figaf Converter (default) adds a GroovyScript step with the Figaf content converter to the migrated IFlow. See Figaf Converter below.

  • Message Transform Bean uses the community package provided by SAP (see article). All channel options are forwarded to it as they are.

2. Figaf Converter

In the migrated IFlow, new GroovyScript step is added. The script calls the content-converter.jar developed by the Figaf team (github project), and the jar is added to the IFlow resources automatically. When several receiver interfaces of an ICO (interface split) use the same file receiver channel, the script is added once and called from every branch of the Parallel Multicast or Router step.

The latest released jar is downloaded from the github project during every migration. If it can’t be downloaded, the jar bundled with Figaf Tool is used instead and the warning Can’t download content-converter.jar from GitHub. A local version of the jar will be used instead. is shown in the migration logs.

Because every migration takes the newest converter, migrating a channel again can produce different XML than the earlier migration when the converter behavior changed in between (for example, since converter 2.2.0 values are trimmed and blank lines are dropped, see Behavior compared to SAP PI). Manual edits of the generated script are lost when the migration is re-run.

3. Channel parameters carried into the script

The generated script contains the conversion settings read from the PI channel.

Channel level:

  • Document Name (xml.documentName) and Document Namespace (xml.documentNamespace);

  • Recordset Name (xml.recordsetName) and Recordset Namespace (xml.recordsetNamespace);

  • Recordset Structure (xml.recordsetStructure) - mandatory, without it the script can’t be generated and a warning is shown in the migration logs;

  • Key Field Name (xml.keyfieldName);

  • ignoreRecordsetName row of the conversion parameters table;

  • File Name (file.targetFileName) for receiver channels.

Substructure options (<Name>.<option> rows of the conversion parameters table):

  • Sender channels (Flat→XML): fieldFixedLengths, fieldNames, keyFieldValue, fieldSeparator, enclosureSign, enclosureSignEnd, fieldContentFormatting, missingLastFields, additionalLastFields.

  • Receiver channels (XML→Flat): fieldFixedLengths, fieldSeparator, addHeaderLine, headerLine, fixedLengthTooShortHandling, beginSeparator, endSeparator.

Values are written as Groovy string literals, so channel values containing quotes or backslashes (for example, keyFieldValue "H" of a quoted CSV channel) don’t break the script.

4. Behavior compared to SAP PI

The converter follows the SAP PI File Content Conversion behavior with the following differences and limitations:

  • The key field is located by Key Field Name at its position in each substructure, so it doesn’t have to be the first field of the line. Enclosure signs are ignored during matching: keyFieldValue H and "H" both match a quoted value.

  • Field values are trimmed by default (fieldContentFormatting=trim). Set fieldContentFormatting to nothing to keep leading and trailing blanks.

  • Blank lines (empty or whitespace-only) are always ignored.

  • A line that matches no substructure is skipped with a warning in the CPI log, as PI does.

  • missingLastFields defaults to add and additionalLastFields defaults to ignore (PI defaults additionalLastFields to error for fixed-length structures). Trailing blanks and a trailing separator count as padding, not as surplus content.

  • The field separator is always treated as literal text, never as a regular expression, so separators like | work.

  • Not supported: enclosureConversion=NO, enclosure escape signs (enclosureSignEscape, enclosureSignEndEscape), keepIncompleteFields, Key Field Type other than case-sensitive (StrS), Document Offset (xml.documentSkipFirstRows), Recordsets per Message, Recordset Sequence = var, processFieldNames=fromFile, keyFieldInStructure=ignore. Such options are reported in the migration logs (see Warning about unsupported options).

5. Warning about unsupported options

In Figaf Converter mode, a channel that uses File Content Conversion options the converter doesn’t apply gets a warning in the migration logs (file content converter step) listing all such options at once, for example:

The channel uses File Content Conversion options that the Figaf content converter does not apply for this conversion direction: xml.documentSkipFirstRows=1, xml.keyfieldType=StrI, HR.lastFieldsOptional=YES, LI.keyFieldInStructure=ignore. The conversion result in CPI can differ from the PI channel for these options.

The migration itself succeeds. Check the listed options and adjust the migrated IFlow if the conversion result depends on them. An option isn’t reported when its value is empty or equals what the converter does anyway: xml.documentSkipFirstRows=0, xml.recordsetsPerMessage=*, xml.keyfieldType=StrS, xml.recordsetStructureOrder=asc, xml.processFieldNames=fromConfiguration, keyFieldInStructure=add, enclosureConversion=YES. Options of the other conversion direction (for example, addHeaderLine on a sender channel) are reported too.