EDIFACTTranslator Component

Properties   Methods   Events   Config Settings   Errors  

The EDIFACTTranslator component converts EDIFACT data to XML and back, streamlining translation between formats.

Syntax

nsoftware.EDISDK.EDIFACTTranslator

Remarks

The component will convert a document from the format specified by InputFormat to the format specified by OutputFormat. This allows for converting to XML from EDI and vice versa.

Before translating from EDI to XML it is recommended to load a schema using the LoadSchema method. This ensures additional information can be included in the XML or JSON document. If a schema is specified the XML will include types and descriptions as element attributes which are useful for interpreting the data.

After calling Translate the resulting output will contain the EDI or XML data as defined by OutputFormat.

Input and Output Properties

The component will determine the source and destination of the input and output based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops. The order in which the output properties are checked is as follows:
  • OutputFile
  • OutputData: The output data is written to this property if no other destination is specified.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

DelimitersContains the delimiters for the EDI Document.
FileWriteModeDetermines how the output file is opened for writing.
InputDataThe EDI message, specified as a string.
InputFileThe file containing the EDI message.
InputFormatThe format of the input data.
OutputDataThe translated EDI data.
OutputFileThe name of the file to write the translated EDI data to.
OutputFormatThe format of the output data.
SegmentSuffixThe suffix that is appended to the end of a segment.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

ConfigSets or retrieves a configuration setting.
LoadSchemaLoads schema information from a file or string data.
ResetResets all properties to their default values.
SetInputStreamThe stream containing the EDI data.
SetOutputStreamSets the output stream where the translated data will be written.
TranslateTranslates the specified data.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

ErrorFires when an error occurs during message processing. Normally, the component fails with an error.
ResolveSchemaFires whenever a new EDIFACT message is encountered and no schema is found for it.
ValidateWarningFires to warn about validation errors.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

CloseStreamAfterTranslateWhether to close the output stream after translation.
EncodingThe character encoding to use for the output EDIFACT document.
UseDescriptionsWhether descriptions will be included in the output XML.

Delimiters Property (EDIFACTTranslator Component)

Contains the delimiters for the EDI Document.

Syntax

public EDIFACTDelimiters Delimiters { get; }

Public ReadOnly Property Delimiters As EDIFACTDelimiters

Remarks

This property contains the delimiters that will be used when parsing the EDIFACT document. If the document uses delimiters other than the default, change the properties of this object to parse the document correctly.

This property is read-only and not available at design time.

Please refer to the EDIFACTDelimiters type for a complete list of fields.

FileWriteMode Property (EDIFACTTranslator Component)

Determines how the output file is opened for writing.

Syntax

public EDIFACTTranslatorFileWriteModes FileWriteMode { get; set; }

enum EDIFACTTranslatorFileWriteModes {
  fwmCreate,
  fwmOverwrite,
  fwmAppend
}

Public Property FileWriteMode As EdifacttranslatorFileWriteModes

Enum EDIFACTTranslatorFileWriteModes
  fwmCreate
  fwmOverwrite
  fwmAppend
End Enum

Default Value

0

Remarks

When OutputFile is set, this property determines how the file will be opened.

fwmCreate (Default)Creates a new file. If the file already exists, the translation will fail.
fwmOverwriteOpens an existing file and overwrites its contents. If the file does not exist, a new file will be created.
fwmAppendOpens an existing file and appends data to the end of the file. If the file does not exist, a new file will be created.

This property is not available at design time.

InputData Property (EDIFACTTranslator Component)

The EDI message, specified as a string.

Syntax

public string InputData { get; set; }

Public Property InputData As String

Default Value

""

Remarks

Set this property to specify the input EDI message as a string. The message can then be parsed with Parse.

This property is not available at design time.

InputFile Property (EDIFACTTranslator Component)

The file containing the EDI message.

Syntax

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

Set this property to specify a file to read the input EDI message from. The message can then be parsed with Parse.

This property is not available at design time.

InputFormat Property (EDIFACTTranslator Component)

The format of the input data.

Syntax

public EDIFACTTranslatorInputFormats InputFormat { get; set; }

enum EDIFACTTranslatorInputFormats {
  ifEDI,
  ifXML
}

Public Property InputFormat As EdifacttranslatorInputFormats

Enum EDIFACTTranslatorInputFormats
  ifEDI
  ifXML
End Enum

Default Value

0

Remarks

The value set here, along with OutputFormat, determines how the data is converted when Translate is called.

Possible values are:

  • 0 (ifEDI)
  • 1 (ifXML)

This property is not available at design time.

OutputData Property (EDIFACTTranslator Component)

The translated EDI data.

Syntax

public string OutputData { get; set; }

Public Property OutputData As String

Default Value

""

Remarks

This property will be populated with the translated data after calling Translate if OutputFile and SetOutputStream are not set.

This property is not available at design time.

OutputFile Property (EDIFACTTranslator Component)

The name of the file to write the translated EDI data to.

Syntax

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

This file specified by this property will be populated with the output after calling Translate if SetOutputStream is not set.

If a file with the specified name already exists Translate will fail unless FileWriteMode is set to "fwmOverwrite" or "fwmAppend".

This property is not available at design time.

OutputFormat Property (EDIFACTTranslator Component)

The format of the output data.

Syntax

public EDIFACTTranslatorOutputFormats OutputFormat { get; set; }

enum EDIFACTTranslatorOutputFormats {
  ofEDI,
  ofXML
}

Public Property OutputFormat As EdifacttranslatorOutputFormats

Enum EDIFACTTranslatorOutputFormats
  ofEDI
  ofXML
End Enum

Default Value

0

Remarks

The value set here, along with InputFormat, determines how the data is converted when Translate is called.

Possible values are:

  • 0 (ofEDI)
  • 1 (ofXML)

This property is not available at design time.

SegmentSuffix Property (EDIFACTTranslator Component)

The suffix that is appended to the end of a segment.

Syntax

public EDIFACTTranslatorSegmentSuffixes SegmentSuffix { get; set; }

enum EDIFACTTranslatorSegmentSuffixes {
  ssNone,
  ssCR,
  ssLF,
  ssCRLF
}

Public Property SegmentSuffix As EdifacttranslatorSegmentSuffixes

Enum EDIFACTTranslatorSegmentSuffixes
  ssNone
  ssCR
  ssLF
  ssCRLF
End Enum

Default Value

3

Remarks

This property determines the suffix that is appended to the end of a segment.

Possible values are:

ssNone (0)No suffix is appended to the segment.
ssCR (1)A carriage return (ASCII 13) is appended to the segment.
ssLF (2)A line feed (ASCII 10) is appended to the segment.
ssCRLF (3)A carriage return followed by a line feed (ASCII 13 and 10) is appended to the segment. This is the default value.

This property is not available at design time.

Config Method (EDIFACTTranslator Component)

Sets or retrieves a configuration setting.

Syntax

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

LoadSchema Method (EDIFACTTranslator Component)

Loads schema information from a file or string data.

Syntax

public void LoadSchema(string fileOrData, string messageName);

Async Version
public async Task LoadSchema(string fileOrData, string messageName);
public async Task LoadSchema(string fileOrData, string messageName, CancellationToken cancellationToken);

Public Sub LoadSchema(ByVal fileOrData As String, ByVal messageName As String)

Async Version
Public Sub LoadSchema(ByVal fileOrData As String, ByVal messageName As String) As Task
Public Sub LoadSchema(ByVal fileOrData As String, ByVal messageName As String, cancellationToken As CancellationToken) As Task

Remarks

This method loads schema information for use when parsing, validating, and translating messages.

The FileOrData parameter can be set to the path of a file containing schema data, or can be set to the contents of a schema file directly.

MessageName can be set to the name of a specific message to load only the specified message's schema information. If left empty or set to "*", the entire schema will be loaded.

Reset Method (EDIFACTTranslator Component)

Resets all properties to their default values.

Syntax

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method resets all properties of the component to their default values as specified in the property definitions.

SetInputStream Method (EDIFACTTranslator Component)

The stream containing the EDI data.

Syntax

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

Call this method to specify a stream to read the input EDI data from. The data can then be parsed with Parse.

SetOutputStream Method (EDIFACTTranslator Component)

Sets the output stream where the translated data will be written.

Syntax

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method sets the output stream for the component. The output stream must be writable. Calling Translate will write the translated EDI data to the specified output stream and close the stream when finished.

Translate Method (EDIFACTTranslator Component)

Translates the specified data.

Syntax

public void Translate();

Async Version
public async Task Translate();
public async Task Translate(CancellationToken cancellationToken);

Public Sub Translate()

Async Version
Public Sub Translate() As Task
Public Sub Translate(cancellationToken As CancellationToken) As Task

Remarks

This method translates the specified data.

Error Event (EDIFACTTranslator Component)

Fires when an error occurs during message processing. Normally, the component fails with an error.

Syntax

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, EDIFACTTranslatorErrorEventArgs e);

public class EDIFACTTranslatorErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As EDIFACTTranslatorErrorEventArgs)

Public Class EDIFACTTranslatorErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally, the component throws an exception.

ConnectionId is the associated client Id, ErrorCode contains an error code, and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

ResolveSchema Event (EDIFACTTranslator Component)

Fires whenever a new EDIFACT message is encountered and no schema is found for it.

Syntax

public event OnResolveSchemaHandler OnResolveSchema;

public delegate void OnResolveSchemaHandler(object sender, EDIFACTTranslatorResolveSchemaEventArgs e);

public class EDIFACTTranslatorResolveSchemaEventArgs : EventArgs {
  public string MessageVersion { get; }
  public string MessageType { get; }
}

Public Event OnResolveSchema As OnResolveSchemaHandler

Public Delegate Sub OnResolveSchemaHandler(sender As Object, e As EDIFACTTranslatorResolveSchemaEventArgs)

Public Class EDIFACTTranslatorResolveSchemaEventArgs Inherits EventArgs
  Public ReadOnly Property MessageVersion As String
  Public ReadOnly Property MessageType As String
End Class

Remarks

This method fires when the component encounters an EDIFACT message it has not loaded a schema for. The parameters of the event can be used to locate the correct schema and load it with LoadSchema.

MessageVersion - The EDIFACT version of the message, such as D97A.

MessageType - The type of message, such as INVOIC.

After the event fires, if the component still doesn't have a matching schema, then it will attempt schema-less parsing of the EDIFACT message.

ValidateWarning Event (EDIFACTTranslator Component)

Fires to warn about validation errors.

Syntax

public event OnValidateWarningHandler OnValidateWarning;

public delegate void OnValidateWarningHandler(object sender, EDIFACTTranslatorValidateWarningEventArgs e);

public class EDIFACTTranslatorValidateWarningEventArgs : EventArgs {
  public long Position { get; }
  public int Line { get; }
  public int Column { get; }
  public string ErrorCode { get; }
  public string ErrorMessage { get; }
  public int ErrorType { get; }
}

Public Event OnValidateWarning As OnValidateWarningHandler

Public Delegate Sub OnValidateWarningHandler(sender As Object, e As EDIFACTTranslatorValidateWarningEventArgs)

Public Class EDIFACTTranslatorValidateWarningEventArgs Inherits EventArgs
  Public ReadOnly Property Position As Long
  Public ReadOnly Property Line As Integer
  Public ReadOnly Property Column As Integer
  Public ReadOnly Property ErrorCode As String
  Public ReadOnly Property ErrorMessage As String
  Public ReadOnly Property ErrorType As Integer
End Class

Remarks

When the component encounters a non-blocking error while validating a document, this event fires with information about the error.

EDIFACTDelimiters Type

The delimiters used in the EDIFACT document.

Remarks

This type contains fields specifying the various delimiters used within the EDIFACT document.

The following fields are available:

Fields

Component
string
Default: ":"

The character used to separate the components in a composite element.

Decimal
string
Default: "."

The character used to separate the integer portion of a numeric value from the fractional portion.

Element
string
Default: "+"

The delimiter used to separate elements within a segment.

Release
string
Default: "?"

The character used to escape other characters within a field. For example, with the default EDIFACT delimiters, "?+" should be considered "+" character that appears within a field, not an element separator.

Repetition
string
Default: "*(syntax 4) or empty(syntax 3)"

The character used to indicate a repeating element or component.

Segment
string
Default: "'"

The character used to terminate a segment.

Constructors

public EDIFACTDelimiters();

Config Settings (EDIFACTTranslator Component)

The component accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

EDIFACTTranslator Config Settings

CloseStreamAfterTranslate:   Whether to close the output stream after translation.

This setting controls whether the output stream is closed after the translation process is complete. The default value is true.

Encoding:   The character encoding to use for the output EDIFACT document.

This setting specifies the character encoding to be used for the output EDIFACT document. The default value is "UTF-8".

UseDescriptions:   Whether descriptions will be included in the output XML.

This setting controls whether descriptions are included in the output XML. The default value is true.

Trappable Errors (EDIFACTTranslator Component)

EDIFACTTranslator Errors

202   Invalid argument.
304   Cannot write to file.
1003   Could not find the selected schema in the chosen file.
1099   Encountered an unexpected segment tag.
1100   Attempted to perform an action while the component was busy, or close an incomplete interchange.
1044   Tried to load an invalid schema file.
1203   Encountered an error while validating the UNA segment.