Update 14 Mar 2016: Revert 2 Jan 2015 change – xml.<StructureName>.processFieldNames is actually correct for StructPlain2XML. Also parameter xml.recordsetsPerMessage is not allowed for StructPlain2XML

Update 9 Oct 2015: Consolidate content – introduction was previously in original blog. Fully move all content to this collaborative document to allow for collaborative effort to maintain/update this reference list

Update 2 Jan 2015: Correction for StructPlain2XML- should be xml.processFieldNames instead of xml.<StructureName>.processFieldNames

Introduction

Performing File Content Conversion (FCC) is a common requirement when developing interfaces that deal with flat file formats. This can be easily accomplished in the File/FTP adapter. However, for other adapter types, this needs to be achieved by adding the MessageTransformBean (MTB) module with conversion class com.sap.aii.af.sdk.xi.adapter.Conversion into the module chain.

However, MTB is not feature-equivalent with the FCC functionality in the File/FTP adapter. Certain parameters that are available for configuration in the File/FTP adapter are not equally supported in MTB. Furthermore, the SAP Help Library online documentation does not fully list down all the available configuration parameters. Therefore, more often than not when working with MTB, it becomes a trial and error exercise.

This blog is an attempt to come up with a list (as comprehensive as possible) of the configuration options available when using MTB. This has been accomplished by decompiling the corresponding JAR package for MTB. Whilst this is on a PI 7.11 system, hopefully most of it will still be applicable for higher releases. Hopefully this will be a helpful reference for those who plan to use MTB in the future.

1) Conversion type: SimplePlain2XML

Parameter Name Default value if parameter not configured Allowed parameter values Additional remarks
xml.skipEmptyFile false
xml.encoding UTF-8
xml.conversionType SimplePlain2XML Required parameter
xml.structureTitle row
xml.fieldFixedLengths Either fieldFixedLengths or fieldSeparator must be populated
xml.fieldFixedLengthType char
xml.fieldSeparator Either fieldFixedLengths or fieldSeparator must be populated
xml.endSeparator nl
xml.beginSeparator
xml.enclosureSign
xml.enclosureSignEnd xml.enclosureSign
xml.enclosureSignEscape
xml.enclosureSignEndEscape xml.enclosureSignEscape
xml.enclosureConversion YES
xml.checkForXMLPredefinedEntities YES
xml.checkForISOControls
xml.lastFieldsOptional NO Deprecated and should not be used with missingLastFields or additionalLastFields
xml.missingLastFields ignore
xml.additionalLastFields
xml.keepIncompleteFields NO
xml.addBeginSeparatorAsField
xml.addEndSeparatorAsField
xml.fieldContentFormatting trim
xml.processFieldNames

fromFile – means that the field name information is located in the header line of the file to be converted.

fromFileWithBlankLine – corresponds to fromFile. After the header line there also follows a blank line or separator that is skipped.

fromConfiguration – means that no header information exits in the file to be converted, but it will be delivered by the present configuration.

notAvailable – means that no field name information is assumed to be in the configuration or in the file to be converted. In this case, the columns in the XML document are identified using a simple counter tag (<columnX> , X=0,1,2…).

Required parameter
xml.documentName
xml.documentNamespace
xml.documentNamespaceScope root
xml.fieldNames Required parameter if xml.processFieldNames = fromConfiguration

2) Conversion type: StructPlain2XML

<StructureName> is per the structure names defined in xml.recordsetStructure. For each structure name listed, configure the corresponding xml.<StructureName>.* parameters.

Parameter Name Default value if parameter not configured Allowed parameter values Additional remarks
xml.skipEmptyFile false
xml.encoding UTF-8
xml.conversionType StructPlain2XML Required parameter
xml.recordsetStructure Required parameter
xml.recordsetStructureOrder asc
xml.allowEmptyRecordsets YES
xml.recordsetName Recordset
xml.recordsetNamespace
xml.recordsetNamespaceScope root
xml.recordsetBeginSeparator
xml.recordsetEndSeparator
xml.documentName
xml.documentNamespace
xml.documentNamespaceScope root
xml.recordsetsPerMessage * Message splitting via MTB is actually not allowed. If this is configured, it will result in an error in the communication channel.
xml.documentSkipFirstRows 0
xml.keyFieldName Required parameter if there is a structure with * in xml.recordsetStructure
xml.keyFieldType Required parameter if there is a structure with * in xml.recordsetStructure
xml.<StructureName>.processFieldNames fromConfiguration

fromFile – means that the field name information is located in the header line of the file to be converted.

fromFileWithBlankLine – corresponds to fromFile. After the header line there also follows a blank line or separator that is skipped.

fromConfiguration – means that no header information exits in the file to be converted, but it will be delivered by the present configuration.

notAvailable – means that no field name information is assumed to be in the configuration or in the file to be converted. In this case, the columns in the XML document are identified using a simple counter tag (<columnX> , X=0,1,2…).

xml.<StructureName>.fieldFixedLengths Either fieldFixedLengths or fieldSeparator must be populated
xml.<StructureName>.fieldFixedLengthType char
xml.<StructureName>.fieldSeparator Either fieldFixedLengths or fieldSeparator must be populated
xml.<StructureName>.endSeparator nl
xml.<StructureName>.beginSeparator
xml.<StructureName>.enclosureSign
xml.<StructureName>.enclosureSignEnd
xml.<StructureName>.enclosureSignEscape
xml.<StructureName>.enclosureSignEndEscape
xml.<StructureName>.enclosureConversion YES
xml.<StructureName>.checkForXMLPredefinedEntities YES
xml.<StructureName>.checkForISOControls
xml.<StructureName>.lastFieldsOptional NO Deprecated and should not be used with missingLastFields or additionalLastFields
xml.<StructureName>.missingLastFields ignore
xml.<StructureName>.additionalLastFields
xml.<StructureName>.keepIncompleteFields NO
xml.<StructureName>.addBeginSeparatorAsField
xml.<StructureName>.addEndSeparatorAsField
xml.<StructureName>.fieldContentFormatting trim
xml.<StructureName>.keyFieldValue Required parameter if there is a structure with * in xml.recordsetStructure
xml.<StructureName>.keyFieldInStructure add
xml.<StructureName>.fieldNames Required parameter if xml.<StructureName>.processFieldNames = fromConfiguration

3) Conversion type: SimpleXML2Plain

xml.encoding
Parameter Name Default value if parameter not configured Allowed parameter values Additional remarks
xml.skipEmptyFile false
UTF-8
xml.conversionType SimpleXML2Plain Required parameter
xml.fieldFixedLengths Either fieldFixedLengths or fieldSeparator must be populated
xml.fieldFixedLengthType char
xml.fieldSeparator Either fieldFixedLengths or fieldSeparator must be populated
xml.endSeparator nl
xml.beginSeparator
xml.checkForXMLPredefinedEntities YES
xml.checkForISOControls
xml.addHeaderLine Required parameter
xml.headerLine Required parameter if xml.addHeaderLine = 3 or 4
xml.absoluteRowWidth 0
xml.fixedLengthTooShortHandling Error

4) Conversion type: StructXML2Plain

<StructureName> is per the structure names defined in xml.recordsetStructure. For each structure name listed, configure the corresponding xml.<StructureName>.* parameters.

Parameter Name Default value if parameter not configured Allowed parameter values Additional remarks
xml.skipEmptyFile false
xml.encoding UTF-8
xml.conversionType StructXML2Plain Required parameter
xml.recordsetStructure Required parameter
xml.<StructureName>.fieldFixedLengths Either fieldFixedLengths or fieldSeparator must be populated
xml.<StructureName>.fieldFixedLengthType char
xml.<StructureName>.fieldSeparator Either fieldFixedLengths or fieldSeparator must be populated
xml.<StructureName>.endSeparator nl
xml.<StructureName>.beginSeparator
xml.<StructureName>.checkForXMLPredefinedEntities YES
xml.<StructureName>.checkForISOControls
xml.<StructureName>.absoluteRowWidth 0
xml.<StructureName>.fixedLengthTooShortHandling Error

References:

For details about the functionality & values related to each parameter, refer to the corresponding parameter listed in the FCC section of the File/FTP adapter below:-

Converting Text Format in the Sender File/FTP Adapter to XML

Converting XML in the Receiver File/FTP Adapter to Text Format

Wiki with step by step sample of configuring FCC on JMS adapter

How To…Content conversion module with J2EE JMS adapter – Process Integration – SCN Wiki

To report this post you need to login first.

4 Comments

You must be Logged on to comment or reply to a post.

  1. Jonathan Ma

    Thanks for putting the documentation together. But this is too simplified. For example, what is keyfieldname? What are you supposed to put in? Unfortunately, the standard SAP doc is even worse than yours.

    I am trying to get the SFTP adapter to parse a simple comma separated file. One day went by and I was struggling with anything and everything. Are you aware of any link or if you can add an example with screenshots?

    (0) 
    1. Eng Swee Yeoh Post author

      Hi Jonathan

      These XML <=> Plain conversions in MTB are comparable with the standard FCC functionality in File/FTP adapter (as well as for SFTP in the latest SP update).

      The reason for this simplified version is that all the field names are already covered in the FCC sections of SAP’s online library, which I’ve also mentioned in the last section References on this document. To document each and every parameter again would be reinventing the wheel. If one is not familiar with any parameter, this document is meant to be used hand-in-hand with SAP’s FCC documentation (not their MTB documentation).

      As for the link to examples, there is already a link to a Wiki which covers this extensively. Did you miss reading the References section at the end?

      Regards

      Eng Swee

      (0) 
  2. Steve Bean

    Hello Eng Swee,

    Thank you for putting this document together, it has already helped me! 🙂

    What would be nice would be if you could add one or two sample conversions and the reuqired parameterization into your document.

    As I am new it would also be good to understand when to use this approach vs. StrictXML2PlainBean and what the limitations are of the different approaches to convert XML to flatfiles (e.g. how are nested XML structure conversions working)

    (0) 
    1. Eng Swee Yeoh Post author

      Hi Steve

      The sample conversions are already available in the Wiki link in the Reference section. The purpose of this document is more to list the available parameters for this module rather than provide a step-by-step guide which is already available on SCN.

      The best way to learn is always to try it out for yourself. Check out the Wiki and try creating a similar scenario to see if it works. If it doesn’t and you can’t figure out why, then you can always post a discussion thread to request for assistance from the community members.

      Regards

      Eng Swee

      (0) 

Leave a Reply