Update 12 Mar 2015: Update links to second part of the series. Parameter for conversion type has been renamed to XML2DeepPlain. Reformat parameter reference section to split parameters applicable for field separator based and fixed length based conversion.
Introduction
In my recent two-part series on using XSLT to handle FCC of deep structures, I mentioned that even after 10 years, the standard FCC functionality provided has not changed significantly. This is unlikely to change as there are other areas of interest which SAP is focusing on these days. Borne out of my preference for reusable and configurable solutions, I decided to challenge myself to come up with an adapter module solution to hopefully fill this gap, if possible maybe once and for all! 
In this two-part series, I will share about DeepFCCBean, the custom adapter module for handling conversion of flat files to deep XML structures and vice versa. As much as possible, the module's behaviors and functionalities are similar to standard SAP's FCC.
This first part covers deep XML to flat file conversion, while the second part covers flat file to deep XML conversion.
Source Code
The full source code can be found in the following public repositories on GitHub.
GitHub repository for DeepFCCBean
GitHub repository for required com.equalize.xpi.util library
EAR deployment file is also available for download from the following GitHub repository release. This EAR can be used for direct deployment in order to use the Adapter Module Bean. Note that this EAR is created based on EJB3.0 version on NWDS 7.31 SP13 Patch 0. For earlier versions of PI, the EJB and EAR file will have to be manually built and compiled using the source code provided.
Module Parameter Reference
Below is a list of the parameters for configuration of the module for deep XML to flat file conversion (conversionType = 'XML2DeepPlain'). Certain parameters will automatically inherit the default values if it is not configured.
The parameters are separated into parameters that are common for this conversion type, and also parameters that are specific for field separator based or fixed length based conversion.
1) Common Parameters
| Parameter Name | Allowed values | Default value | Remarks |
|---|---|---|---|
| conversionType | DeepXML2Plain XML2DeepPlain | Required field. Determines conversion type | |
| encoding | UTF-8 | Defines encoding of output plain text file | |
| recordsetStructure | Required field. List of substructure names separated by comma | ||
| <StructureName>.endSeparator | System specific new line | Defines end of record separator | |
| messageLog | pre, post | Saves a log version of the message that is viewable in Message Monitor
| |
| logLocation | default | Name of log version when messageLog is populated |
2) Field Separator Conversion Parameters
| Parameter Name | Allowed values | Default value | Remarks |
|---|---|---|---|
| defaultFieldSeparator | Defines a default field separator for all substructures that do not have <StructureName>.fieldSeparator explicitly configured Note: Cannot be used together with <StructureName>.fieldFixedLengths | ||
| <StructureName>.fieldSeparator | Either <StructureName>.fieldFixedLengths or <StructureName>.fieldSeparator must be populated |
3) Fixed Length Conversion Parameters
| Parameter Name | Allowed values | Default value | Remarks |
|---|---|---|---|
| <StructureName>.fieldFixedLengths | Integer separated by commas | Either <StructureName>.fieldFixedLengths or <StructureName>.fieldSeparator must be populated | |
| <StructureName>.fixedLengthTooShortHandling | Error, Cut, Ignore | Error | Applicable when <StructureName>.fieldFixedLengthsis configured. Determines behavior when actual length of field exceeds corresponding length configured:
|
Similar to standard FCC functionality, fieldSeparator and endSeparator parameters support non-printable ASCII characters as follows:
- characters encoded as hexadecimal values in the form of '0xHH' (including quotation marks)
- line break specified using 'nl' (including quotation marks)
Example Scenarios
Here are some example scenarios of the behavior of the conversion based on different configuration options.
Scenario 1
3 level deep input XML with delimited output
Field separator: Delivery and Order using comma. Item using tab (specified in hexadecimal)
End separator: Delivery has additional ZZZZ followed by line break. Order and Item not specified therefore using default line break
Module parameters
| Parameter Name | Parameter Value |
|---|---|
| conversionType | XML2DeepPlain |
| recordsetStructure | Delivery,Order,Item |
| Delivery.fieldSeparator | , |
| Delivery.endSeparator | ZZZZ'nl' |
| Item.fieldSeparator | '0x09' |
| Order.fieldSeparator | , |
Result
| Input | <?xml version="1.0" encoding="UTF-8"?> <ns0:MT_Deep xmlns:ns0="urn:equalize/DeepFCC"> <Delivery> <Type>D</Type> <DeliveryNo>Delivery2</DeliveryNo> <Order> <Type>O</Type> <DeliveryNo>Delivery2</DeliveryNo> <OrderNo>Order2_A</OrderNo> <Item> <Type>I</Type> <OrderNo>Order2_A</OrderNo> <ItemNo>10</ItemNo> <Quantity>90</Quantity> </Item> <Item> <Type>I</Type> <OrderNo>Order2_A</OrderNo> <ItemNo>20</ItemNo> <Quantity>80</Quantity> </Item> </Order> </Delivery> </ns0:MT_Deep> |
| Output |  |
Scenario 2
3 level deep input XML with fixed length output
Length too short handling: Order set to ignore so long fields can potentially push subsequent fields. Item set to cut to maximum configured length
Module parameters
| Parameter Name | Parameter Value |
|---|---|
| conversionType | XML2DeepPlain |
| recordsetStructure | Delivery,Order,Item |
| Delivery.fieldFixedLengths | 5,10 |
| Order.fieldFixedLengths | 5,5,10 |
| Order.fixedLengthTooShortHandling | Ignore |
| Item.fieldFixedLengths | 5,5,10,10 |
| Item.fixedLengthTooShortHandling | Cut |
Result
| Input | <?xml version="1.0" encoding="UTF-8"?> <ns0:MT_Deep xmlns:ns0="urn:equalize/DeepFCC"> <Delivery> <Type>D</Type> <DeliveryNo>Delivery2</DeliveryNo> <Order> <Type>O</Type> <DeliveryNo>Delivery2</DeliveryNo> <OrderNo>Order2_A</OrderNo> <Item> <Type>I</Type> <OrderNo>Order2_A</OrderNo> <ItemNo>10</ItemNo> <Quantity>90</Quantity> </Item> <Item> <Type>I</Type> <OrderNo>Order2_A</OrderNo> <ItemNo>20</ItemNo> <Quantity>80</Quantity> </Item> </Order> </Delivery> </ns0:MT_Deep> |
| Output |  |
Scenario 3
Finally for the third scenario, we will use the same input file that was used in the XSLT approach. Actual configuration and testing screenshots are shown.
Default field separator for all substructures is used.
A log version of the message payload after conversion is saved.
Module configuration on an SFTP receiver channel.
The 'plain' log version shows the payload after conversion of deep XML to flat file.
The audit log shows the trace of steps being executed by the module.
Conclusion
With DeepFCCBean, content conversion of deeply nested flat files no longer require new custom development.
Do note that it is technically possible for DeepFCCBean to handle the flat files that can be converted by standard FCC. However, it is not the intention of DeepFCCBean to replace SAP's standard functionality, but to complement it in handling deep structures. As such, for flat files that can be converted by standard FCC, it is recommended that standard FCC is used.
Upcoming will be the second part of this series covering flat file to deep XML conversion with DeepFCCBean. Watch this space!
Second part is now out at DeepFCCBean - The better FCC at meeting your deep (structure) needs! (Part 2 - Flat File to Deep XML)