Module for EDI 9.12 | Building Services with EDI Module | Part I WmEDI Package | WmEDI Core Services | Summary of Elements in this Folder | wm.b2b.edi:convertToString
 
wm.b2b.edi:convertToString
WmEDI. Converts an IS document (IData object) to a String, based on a flat file schema that you specify.
The difference between this service and the pub.flatFile:convertToString service is that it handles EDI documents. For EDI documents, it will optionally fill in the counters and control numbers if they are empty. For example, if SE01 is null, it will fill in the segment count. If you want to control the counters or control numbers, modify the IS document (IData object) prior to invoking this service to convert it to a String.
Note:
To convert TRADACOMS documents, use the wm.b2b.edi.tradacoms:convertToString service instead of this service.
Input Parameters
values
Document The IS document (IData object) object that you want to convert to a String.
EDItemplate
Document (optional) This input parameter is provided only for backwards compatibility. It should contain a single name/value pair that is a String named templateName with the value set to the namespace name of the flat file schema to use for the conversion. This is the output from the wm.b2b.edi.templateMgr:getTemplate service. Do not specify an EDI template.
You must specify ffSchema, EDItemplate, or nsRecord. The parameters nsRecord and EDItemplate is deprecated, so it is recommended that you use ffSchema.
ffSchema
String The fully-qualified namespace name of the flat file schema to use to convert the specified IS document (IData object) (in values) to a String.
You must specify ffSchema, EDItemplate, or nsRecord. The parameters nsRecord and EDItemplate is deprecated, so it is recommended that you use ffSchema.
spacePad
String How you want the resulting String to be justified. Specify one of the following:
Value
Meaning
left
Left justify.
right
Right justify.
none
No justification. This is the default.
noEmptyTrailingFields
String Whether to remove empty trailing fields from records. The convertToString service only uses this parameter for records that have delimited fields. Specify true or false.
Value
Meaning
true
The convertToString service removes empty trailing fields from the output. For example, a record with empty trailing fields might look like the following: AAA*01*02! (where ! is the segment terminator). This is the default.
false
The convertToString service does not remove empty trailing fields. Instead it uses the field separator to denote an empty field. For example, a record with empty trailing field might look like the following: AAA*01*02********!(where * is the field separator and ! is the segment terminator).
nsRecord
String (optional) The fully-qualified name of the IS document type on which the resulting String will be based. If you specify nsRecord, the convertToString service ignores the ffSchema parameter.
You must specify ffSchema, EDItemplate, or nsRecord. The parameters nsRecord and EDItemplate is deprecated, so it is recommended that you use ffSchema.
Segment_terminator
String (optional) The segment terminator character that you want the convertToString service to append to the end of each record in the output String.
Field_separator
String (optional) The field separator that you want the convertToString service to insert between each field for each segment in the output String.
Subfield_separator
String (optional) The subfield separator that you want the convertToString service to use for composite elements.
FormatInfo
Document (optional) Values you want the convertToString service to pass unmodified to all format services it invokes.
releaseCharacter
String (optional) The character you want the convertToString service to use as an escape character. If one of the characters that you specify for Segment_terminator, Field_separator, or Subfield_separator appears in field or subfield, the convertToString service will prefix the character with this escape character before writing it to the output String.
outputFileName
String (optional) The name of the file to which you want the String output written. If you do not specify outputFileName the output is not written to a file.
encoding
String (optional) The encoding of the InputStream passed in to edidata. The default is UTF-8.
startAt
String Allows the convertToString service to start at a specific record in the flat file schema used to create the output string. Specify the path to the element where you want to start composing the output string.
sortInput
String (optional) Whether you want the service to sort the input records to match the flat file schema specified in ffSchema. When set to true (the default), this flag is useful in either of the following cases:
*If the data in values is not in the same order as defined by ffSchema.
*If EDI transactions contain two segments with the same name at the same level, but with distinctly different structures. For more information, see "Usage Notes" at the end of this section.
true
You want the service to sort the input records. This is the default.
Important:
If you select to sort the input records, note that:
*The service will run slower.
*All undefined records will be sorted after the defined records.
*The order of the undefined records appear in the final document is random.
*If there are multiple records at the same level with the same name, the order they appear in the final document is random.
false
You do not want the service to sort the input records.
countSegments
String Whether to count the number of segments written to the output file.
true
The convertToString service counts the number of segments written to the output file and returns that number in the output parameter segmentCount. This is the default.
false
The convertToString service does not count the number of segments written to the output file.
RepeatingField_separator
String (optional) The field separator that you want the convertToString service to insert between repeating fields of an EDI document.
Module for EDI recognizes both repeating simple fields and repeating composite fields.
Output Parameters
string
String The output String that represents the data specified in the values input parameter.
errorArray
String List Error messages describing the errors that the convertToString service encountered during conversion. If the convertToString service did not encounter errors, errorArray is null.
segmentCount
String The number of records written; only returned when countSegments is true.
Usage Notes
*You can specify the terminator or separator as a character (e.g., *), as unicode (e.g., \u001c), as a hex character (e.g., 0x15), as an octo character (e.g., 027), or as a decimal character (e.g., 21).
*When you use the convertToString service to convert an IS document (IData object) to an EDI ANSI X12 String, this service automatically:
*Generates a control number for each header and trailer if the control number is null.
*Calculates and replaces segment counts, group counts, and document counts to ensure that their values are accurate (only if the count is blank or null).
*You can also use sortInput to handle EDI transactions that contain two segments with the same name at the same level, but with distinctly different structures. For example, assume that the flat file schema for UNEDIFACT 97A INVOIC shown below contains two TAX segments:
UNH
.
TAX (in header)
LIN
TAX (in details)
.
UNT
The first TAX segment is optional. If only the second TAX segment is present in the file, the output of the wm.b2b.edi:convertToValues service will differ, depending on the value of the sortInput flag.
*If sortInput is set to true, then the convertToString service assumes that the input IData is out of sequence. The convertToString service will sort the input record so that the TAX segment is in the header of the output document.
*If sortInput is set to false (the default), then the TAX segment will appear in the output document after the LIN segment.
Example
See the Tutorial.XMLtoEDI:processXMLSource service in the WmEDIsamples package, which is located in the Technical Communities area on the Empower Product Support website.