Update 5 Nov 2019: Add new parameter trim to trim XML text nodes
Update 4 Jul 2019: Add parameters defaultEnclosureSign & defaultEnclosureSignEscape for CPI version.
Update 2 Nov 2018: Default parsing in CPI will be using SAX-based XmlSlurper.
Update 4 Sep 2018: Now available in CPI as well.
Update 25 Mar 2015: DeepFCCBean has been refactored to be part of FormatConversionBean. Parameter conversionType replaced with converterClass. Note that some of the screenshots are not updated to reflect the new parameter converterClass.
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
Refer to following blog on location of source code and/or EAR deployment file.
FormatConversionBean - One Bean to rule them all!
Usage of Module in Communication Channel
Module Processing Sequence
| Number | Module Name | Type | Module Key |
|---|---|---|---|
<Depending on position of module in chain> 1) Asynchronous scenario, Normally before the last module in channels 2) Synchronous scenario, Before last module to convert request payload After last module to convert response payload | Custom_AF_Modules/FormatConversionBean | Local Enterprise Bean | <Any Arbitrary Value> |
Module Parameter Reference
Below is a list of the parameters for configuration of the module for deep XML to flat file conversion (conversionType = 'com.equalize.xpi.af.modules.deepfcc.DeepPlain2XMLConverter'). 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 |
|---|---|---|---|
| converterClass | PI - com.equalize.xpi.af.modules.deepfcc.XML2DeepPlainConverter CPI - com.equalize.converter.core.XML2DeepPlainConverter | Required field. Determines conversion class | |
| 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 | |
| useDOM | Y, N | N | Available only in CPI Parser used in parsing input XML
|
| trim | Y, N | N | Available only in CPI Trim whitespace in XML text nodes during parsing |
| messageLog | pre, post | Saves a log version of the message that is viewable in Message Monitor
Available only in PI | |
| logLocation | Name of log version when messageLog is populated. Location defaulted to value in messageLog if logLocation not populated. Available only in PI |
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 | ||
| defaultEnclosureSign | Specify a string that acts as a text delimiter for each field. For example: " (double quote character). Available only in CPI | ||
| defaultEnclosureSignEscape | Specify a string that replaces the text delimiter defaultEnclosureSign if it occurs within a field that it delimits. For example: "" will replace ". Available only in CPI | ||
| <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 |
|---|---|
| converterClass | com.equalize.xpi.af.modules.deepfcc.XML2DeepPlainConverter |
| 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 |
|---|---|
| converterClass | com.equalize.xpi.af.modules.deepfcc.XML2DeepPlainConverter |
| 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...
- SAP Managed Tags:
30 Comments
