Overview

This guide explains File Content Conversion (FCC) in SAP PI/PO end to end. It helps you choose the right approach, configure it correctly, and run it reliably in production.

FCC is a feature of the SAP PI/PO File Adapter. It transforms flat files (CSV or fixed-length) into XML on the sender side. It also renders XML back into flat files on the receiver side, using adapter-level parameters.

You will learn how to model recordsets and tune parameters like fieldFixedLengths, fieldSeparator, enclosureSign, and keyFieldValue. You will also handle multi-recordset outputs such as header–item–trailer.

We cover a decision framework that contrasts FCC with MessageTransformBean and StrictXml2PlainBean. You will get performance guidance for large files, character encoding and locale pitfalls, QoS and reprocessing, PGP encryption, a troubleshooting catalog, and migration notes for SAP Integration Suite/CPI.

For canonical parameter semantics and examples, refer to the official SAP Help on File Content Conversion in your release.

Core concepts and prerequisites

This section aligns terminology and objects. The goal is for your configurations to map cleanly to runtime behavior and message mappings.

FCC revolves around recordsets. These are logical groups of fields in a line or block. They use field delimiters or fixed-length segments. Optional headers and trailers are supported. These convert to or from XML segments that your message mapping consumes or produces.

On the sender side, the FILE adapter reads from a directory and applies FCC to produce XML. That XML flows to mapping, routing, and target systems.

On the receiver side, XML from mapping is converted to delimited or fixed-length lines. The adapter then writes to disk or transfers via SFTP/FTPS/TLS.

In IR/ESR you still define message types and mappings. FCC determines how the raw file becomes a structured XML payload, and vice versa.

A simple example is a CSV order file. Each line becomes an <Item> element under an <Orders> root. A header record becomes a distinct <Header> element based on keyFieldValue.

Validate your prerequisite objects (Data Types, Message Types, Service Interfaces). Test a sample file in your sender channel’s FCC preview to confirm structure recognition.

FCC vs MessageTransformBean vs StrictXml2PlainBean vs custom mappings: a decision framework

This section helps you choose the right transformation approach. Consider your file structure, volume, and maintainability goals.

FCC is the default for many “CSV to XML/flat” interfaces in SAP PI/PO. Adapter modules and custom code can be better for some edge cases or operational needs.

Start by assessing structure regularity. Ask if the format is strictly delimited or fixed, or if it is nested or irregular.

Consider volume and throughput targets. Factor in security needs and module chaining, such as PGP.

Account for operational constraints like idempotency and reprocessing. These often drive the final choice.

FCC shines when your files are regular and modelable via adapter parameters. It fits well when the structure maps cleanly to XML segments.

MessageTransformBean and StrictXml2PlainBean can reduce configuration overhead. They work for straightforward XML↔flat use cases handled entirely in the module chain.

If your format is irregular, multi-level nested, or highly conditional, consider custom logic. You may need streaming transformations with fine-grained control.

As a quick test, mock a representative 1–2 MB file. Implement both FCC and a module-based conversion to compare simplicity and output fidelity.

When to prefer FCC (strengths, limitations, version caveats)

This subsection clarifies why FCC is the workhorse for flat files in SAP PI/PO. It also shows where it may struggle.

Choose FCC when you have consistent delimited or fixed-length records. It works well when you need multi-recordset routing via keyFieldValue.

FCC keeps transformation close to the File Adapter. Your message mapping then stays on normalized XML.

FCC can be less flexible for nested or context-sensitive formats. Examples include optional blocks that span multiple lines.

It also lacks strict custom validations beyond parameter checks. That can be limiting for complex contracts.

Some parameters and behaviors differ across XI/PI 7.1x and PO 7.5. A few are obsolete or changed in semantics in the PO 7.5 line.

Always verify behavior on your target release. Do not assume old defaults still apply.

In practice, the most frequent pitfalls come from fieldFixedLengths. enclosureSign handling is another common source of errors.

Problems spike when input data contains delimiters in quoted text. Test with real samples, including boundary cases.

Cover embedded separators, long text fields, and missing optional fields in your tests.

When to use adapter modules (MessageTransformBean, StrictXml2PlainBean)

This subsection outlines when adapter modules outperform FCC for simplicity or specific behavior.

MessageTransformBean can convert between XML and flat formats in the module chain. It uses clear module parameters.

StrictXml2PlainBean enforces strict XML-to-plain rendering with predictable output. It helps when downstream systems require exact column positions.

Modules are a good fit when you do not want FCC parameters in channels. They standardize conversion logic across channels without separate FCC blocks.

Modules also pair neatly with security modules in concise chains. They can simplify XML to CSV generation when your XML structure is flat.

Review the adapter module documentation in SAP Help for exact parameter names and ordering. Validate by enabling module trace temporarily to confirm transformed payloads before writing files.

When custom Java/XSLT wins

This subsection explains scenarios where custom mapping or Java modules are safer and faster long term.

If your file structure is irregular or deeply nested, custom code helps. It also helps when parsing must be context-sensitive across variable lines.

In these cases, FCC and modules become brittle. A controlled parser is often more reliable.

At very high volumes or very large files, a streaming custom parser can outperform generic FCC or modules. It avoids full buffering and offers backpressure to the adapter engine.

Custom code also enables advanced security or compliance logic. Examples include inline digital signatures, tamper-evident hashes, or content inspection.

These features are not available in standard FCC or module features. Custom code covers those gaps.

Keep in mind that custom code raises maintenance overhead. Encapsulate it behind clear interfaces and add robust unit tests with representative files.

Pilot your custom approach with a 100 MB sample. Compare memory and CPU usage to FCC before committing.

Sender-side configuration: flat file to XML with FCC

This section provides a step-by-step approach to Sender Adapter FCC configuration. The goal is to turn flat files into clean XML for mapping.

The key is to model recordsets and fields unambiguously. Set separators, enclosures, and fixed lengths to match the producer’s specification.

After configuring, use the adapter channel’s test or a controlled QA run to verify output. Check that each input line maps to the intended XML nodes and that special characters are preserved.

Ensure your ESR message mapping expects the same XML structure that FCC generates. As a sanity check, view the raw file in a hex-aware editor. Also review the post-FCC XML in message monitoring to confirm separators and encoding.

Recordset modeling and parameter essentials

This subsection maps essential FCC parameters to predictable XML structures. The goal is to reduce trial-and-error.

For delimited files, fieldSeparator defines how the adapter splits fields. fieldNames defines the element names in the generated XML.

enclosureSign ensures separators within quoted strings are treated as literals. These are not split points.

For fixed-length files, fieldFixedLengths enforces positional parsing. It pairs with alignment and padding expectations at the producer.

Getting lengths wrong by even one character cascades errors across the rest of the line. Validate lengths early.

For multi-recordset inputs, use keyFieldValue tied to a keyFieldName. This may be the first character of the line.

That routes lines to separate recordsets like Header, Item, and Trailer. It enables a clean header–item–trailer XML.

beginSeparator and endSeparator ensure correct line detection. This matters across platforms where CRLF vs LF differs.

Test a single input file containing all recordset types. Confirm the resulting XML has one node per expected line and recordset.

Handling structure deviations and optional fields

This subsection shows how to make FCC resilient when files deviate modestly from the contract.

If certain trailing fields are optional, configure your recordset structure accordingly. Decide whether missing trailing fields should be empty values or errors in the sender channel.

Handle lines with extra separators or truncated fixed-length data explicitly. Adjust fieldSeparator rules, enclosureSign expectations, or fixed-lengths to match real producer behavior.

For delimited files with occasional missing middle columns, validate the producer’s quoting rules. Determine whether the producer always quotes empty fields.

Mismatches here often lead to field-shifting and incorrect XML mapping. Catch them with targeted samples.

Some parameters have evolved or become obsolete in PO 7.5 compared to PI 7.1x. Cross-check behavior on your target release before relying on legacy defaults.

As a practice, keep a “rogue sample” folder. Validate FCC against worst-case lines in mock test runs.

Receiver-side conversion: XML to flat/CSV, multi-recordset outputs, and trailers

This section focuses on emitting high-quality flat files from XML using Receiver Adapter FCC. It includes multi-recordset output and trailers.

The goal is to produce files that are byte-for-byte acceptable to downstream systems. Pay attention to separators, padding, and trailers.

Start by ensuring your message mapping outputs XML nodes in the right order. This is typically Header, multiple Items, and then Trailer.

For CSV, configure fieldSeparator and enclosureSign. Use endSeparator matching the operating system expectations of the consumer.

For fixed-length outputs, define fieldFixedLengths. Ensure padding and alignment follow the contract.

Numeric fields often require leading zeros. Text fields often require space padding.

Verify the result with a hex viewer. Confirm line endings and padding at the byte level.

Conditional fields, padding, and separators

This subsection explains how to handle fields that appear only under certain conditions. It also shows how to enforce padding and separators.

Your mapping should emit elements only when necessary. FCC can render absent elements as empty fields for CSV. It can also render padded spaces for fixed-length outputs.

Use alignment and padding parameters to right-align numeric fields. Left-align text fields as required.

Ensure numerics get zero-padding. Ensure text gets space-padding per the receiver spec.

Locale-aware formatting matters for decimals and thousands separators. Normalize values in mapping.

Ensure FCC does not add locale-specific formatting. Keep control of number formats in mapping.

For enclosureSign, quote fields that can contain separators or newlines. This avoids parsing errors when receivers load files into spreadsheets.

Run a golden-file diff in QA after each change. This guarantees byte-level stability of output.

Character encoding and locale handling

This section prevents subtle data corruption. It aligns encoding, BOM, and locale behavior across systems.

Always set the adapter to the partner’s expected encoding. Common choices are UTF-8, UTF-16LE/BE, or a specific SAP code page.

This ensures characters like “ä/ß/ø” survive round trips. Mismatched encodings often break these characters.

UTF-8 with no BOM is widely accepted. Per the Unicode BOM FAQ, a UTF-8 BOM is legal but not required.

Some software breaks when a UTF-8 BOM appears unexpectedly. Use it only if the partner requires it.

If the partner mandates BOM for UTF-16, choose the correct endianness (LE vs BE). The BOM indicates byte order automatically.

In PI/PO, incorrect encoding presents as garbled diacritics or parsing exceptions. Match the sender/receiver encoding explicitly rather than relying on server defaults.

Verify with a hex viewer. For locale, standardize decimal and thousand separators in mapping.

Ensure line endings (LF vs CRLF) match the receiver’s platform. This avoids row-count mismatches.

Performance and large-file handling

This section provides patterns to process 100 MB–1 GB files safely. Avoid timeouts and out-of-memory issues by design.

The rule of thumb is to stream and segment where possible. Avoid unnecessary payload logging.

Tune adapter engine memory and thread pools for sustained throughput. Validate under load.

For sender FCC, prefer delimited parsing with enclosureSign. This avoids regex-heavy logic and reduces CPU spikes.

Validate constant memory by limiting audit log payload persistence. On receiver FCC, generate files sequentially.

Offload encryption and compression to dedicated modules that stream. This reduces heap spikes and GC pressure.

Where business rules allow, split very large files into chunks. You can also schedule multiple channels with non-overlapping file name patterns.

Parallelization lowers latency but must preserve ordering semantics. Do not violate business sequence rules.

After tuning, run soak tests with realistic 100 MB and 1 GB files. Monitor adapter engine CPU, heap, GC pauses, and channel throughput.

Benchmark methodology and sample configurations

This subsection proposes a repeatable way to compare FCC, MessageTransformBean, StrictXml2PlainBean, and custom code in your context.

After benchmarking, choose the simplest approach that meets performance SLOs with headroom. If FCC is within 10–15% of a custom implementation and easier to operate, prefer FCC.

Keep the test harness in your repo. Re-run on patch upgrades to catch regressions early.

Quality of Service, idempotency, and safe reprocessing

This section ensures that file-based interfaces remain reliable. It covers retries, duplicates, and restarts.

In SAP PI/PO, choose Exactly Once (EO) for deduplicated delivery. Use Exactly Once In Order (EOIO) when strict order is mandatory.

Understand that EOIO trades throughput for ordering guarantees. See SAP Help: Quality of Service for details.

At the file boundary, idempotency is your responsibility. Files can be retried or re-delivered.

Embed unique identifiers into payloads. Combine file name, timestamp, and sequence if helpful.

Archive processed files with a retention policy. This supports audits and safe reprocessing.

For large files, use checkpointing patterns. Split files logically (for example, per 10k records).

This allows failed chunks to be reprocessed. It avoids duplicating completed records.

If the receiver cannot tolerate duplicates, add business-layer de-duplication. Key it by a batch ID and record index.

Test reprocessing by forcing a mid-transfer failure. Prove that your archive and checkpoint logic prevent data loss or duplication.

Security hardening for file interfaces

This section raises the security baseline. The goal is to protect data at rest and in transit end to end.

Always use SFTP, FTPS, or HTTPS/TLS to secure transport. Validate server host keys and certificates.

Rotate keys on a set cadence. Track expiry to avoid surprises.

If you require payload encryption, use PGP modules. Encrypt outbound files and decrypt inbound files.

OpenPGP is standardized by RFC 4880. Follow the standard for compatibility.

Manage private keys centrally with strict access controls. Rotate public keys from partners and track revocation.

Implement tamper detection via digital signatures or detached signature files. Enable audit logging that captures channel, file name, correlation IDs, and outcomes.

Follow OWASP Logging recommendations. Test logging outputs under failure.

After each security change, run an end-to-end test with invalid keys. Ensure failures are clear and recoverable.

PGP with FCC: module sequencing and failure recovery

This subsection clarifies correct module order. It ensures decryption and encryption occur at the right stage relative to FCC.

For inbound files, the sequence is typically decrypt → convert (FCC) → map. The sender module chain should first decrypt the payload.

Then apply FCC so the adapter sees the clear-text structure. This keeps parsing correct.

For outbound files, map → convert (FCC) → encrypt is standard. The receiver module chain should transform XML to flat and then encrypt.

This avoids exposing structure changes post-encryption. It also ensures consistent payloads.

Set module timeouts to accommodate large files. Enable retries only where idempotency is guaranteed.

On failure, quarantine partial files. Keep original inbound files in a “failed” folder for safe reprocessing.

Validate by simulating wrong keys or expired certificates. Confirm that no clear-text residue is left on disk.

Troubleshooting playbook: common FCC errors and fixes

This section gives quick resolutions by mapping error messages to likely parameter issues. Use the following compact triads to diagnose and fix quickly:

After you apply a fix, run a limited-file test with 10–100 lines. Include the failing records in the sample.

Confirm the adapter produces correct XML or flat output. Keep annotated samples alongside your channel configuration for future regressions.

Error signatures linked to parameters

This subsection links recurring parsing failures to their most influential FCC parameters.

Separator-related issues nearly always trace back to fieldSeparator and enclosureSign. This is common when fields legitimately contain delimiters or newlines.

The remedy is consistent quoting and escape semantics across producer and consumer. Fix both ends if needed.

Fixed-length errors correlate with fieldFixedLengths and alignment or padding conventions. Getting one field wrong cascades down the line.

Misrouted records frequently indicate keyFieldValue or keyFieldName position mismatches. Verify the discriminator character or substring indices.

Line-ending anomalies, such as double lines or truncated lines, point to beginSeparator or endSeparator mismatches. LF and CRLF differences often cause this.

As a verification habit, compare raw line byte counts to your declared lengths. Run a binary diff on known-good files after parameter changes.

Monitoring and operations

This section establishes an operations baseline. You can then detect issues fast and maintain compliance.

In PO 7.5, use NWA/Adapter Engine monitoring. Watch channel availability, backlog, average processing time, and error trends.

Enable alerting to email or a central incident system. Keep notifications actionable and concise.

Set logging to the lowest level that still supports incident diagnosis. Avoid payload logging in production unless strictly necessary.

This reduces risk and overhead. It also improves performance.

Implement file retention and archiving policies. Include daily rotations and quarantine folders for failed or suspicious files.

Add automatic cleanup to prevent disk pressure. Review retention rules regularly.

For capacity planning, track throughput (files/day and MB/s), error rates, and average file sizes over time. These metrics inform memory and thread tuning.

They also justify horizontal scaling if needed. Run a quarterly failover and reprocessing drill to confirm your runbooks work when it matters.

Testing and CI/CD for FCC and mappings

This section shows how to prevent regressions with automated, sample-driven tests.

Assemble a curated dataset of sample files. Include normal, edge, and pathological cases.

Cover embedded separators, missing fields, and long text. Store expected XML and flat outputs as golden files.

Automate tests that run FCC in a controlled environment. Use a test channel or a lightweight harness.

Diff outputs byte-for-byte for receiver-side tests. Diff node-for-node for sender-side XML.

Integrate tests into your CI pipeline, such as Jenkins or Azure DevOps. Trigger verification on every ESR/ID change or channel parameter update.

This protects against silent breaks from innocuous changes. It also documents behavior.

For mappings, use ESR mapping unit tests with varying contexts. Ensure stable outcomes across PI/PO patches.

Before go-live, run a volume test with production-like files. Capture performance baselines for future comparison.

Version differences: XI/PI 7.1x vs PO 7.5

This section highlights behavior changes and obsolete parameters. It helps you avoid surprises during upgrades.

PO 7.5 consolidates on the Java stack. It brings changes in adapter engine behavior, logging, and some FCC defaults.

Some older parameters in XI/PI 7.1x are deprecated or altered in semantics. Do not assume parity.

The safest approach is to recreate channels in a sandbox on the target version. Validate FCC outputs against golden files.

Pay special attention to enclosure handling and fixed-length padding. These often change.

Module availability and versions may differ. Confirm MessageTransformBean and StrictXml2PlainBean parameters on the target system.

Review SAP’s release notes and current documentation. Look for flags on obsolete or changed parameters.

Keep a migration log noting every parameter that required adjustment and why. Future maintainers will benefit.

Migration to SAP Integration Suite/CPI

This section maps PI/PO FCC concepts to SAP Integration Suite/CPI equivalents. It also flags feature gaps.

In Cloud Integration you achieve similar results using message transformers. Use flow steps such as CSV-to-XML and XML-to-CSV converters.

Handle file transport via the CPI File/SFTP adapters with content conversion features. Align parameters with partner contracts.

While CPI offers comparable CSV and fixed-length conversions, some adapter-level features differ. Module chains and error handling also differ from PI/PO.

Plan for changes in streaming behavior and module ordering. Prototype early to validate parity.

For PGP, use CPI’s security components and decrypt or encrypt steps. Keep the same decrypt→convert and convert→encrypt patterns.

Review the official SAP Integration Suite (Cloud Integration) documentation. Confirm current transformer capabilities and adapter parameters.

Prototype a representative flow early to validate parity. Budget for functional equivalence testing and performance tuning.

Pay extra attention to very large files and strict fixed-length outputs. These often need tuning.

Next steps and resources

This section closes with actionable steps and authoritative references. It helps you move from reading to doing.

Start by implementing a pilot FCC sender and receiver pair. Use a real sample file.

Then add security hardening, QoS, and monitoring in layers. Run automated tests on every change.

Use these resources as your canonical references and for deeper dives:

As a final checklist, confirm your Sender Adapter FCC configuration with fieldSeparator or fieldFixedLengths. Validate encoding with a hex viewer.

Benchmark with 10, 100, and 1000 MB samples. Enable EO or EOIO according to business needs.

Wire up PGP and TLS before promoting to production. With these practices, File Content Conversion (FCC) in SAP PI/PO remains predictable, secure, and performant across the entire lifecycle.