Config / Mappings / The X12 Converter

The X12 Converter

Anveo EDI Connect supports the import and export of X12 files. The converter is using the same code base as the EDIFACT converter, but behaves a little bit different, due to the format differences and that we cannot access the X12 standard directly.

We assume that you know how to work with mapping lines and how to access the EDI properties.

Mapping Create and Update Wizard

The X12 converter has a powerful assistant to create the mapping structure from an example file. For copyright reasons we cannot provide the X12 standard with the product and thus also can’t detect loops, field length etc. automatically. We do however create one line for each segment, composite and data element. You can add the missing information later on.

Before starting the assistant, you should check the header properties and select the correct control characters.

Commands

The X12 converter supports a few special commands. The available command are:

EXIT

This command will leave the current mapping, without writing the current table record. Use with caution.

RUNASYNC

This command allows you to start a different mapping, like a post-processing. But you do not require table data to pass to the next mapping and you can specify the mapping dynamically. This is mainly used in pre-process mappings, where you call a different X12 mapping, based on the message type or sender. The command with the name SkipSegments can help to skip unnecessary parts of the X12 file and keep your mapping small.

SkipSegements

This command allows you to skip all X12 data up to a specified segment. This is mainly used in pre-process mappings, where you only want to parse, for example, the header and skip the rest of the file, because it will be processed by a different mapping. It is also possible to use this, to skip certain message types, while processing others in the same mapping.

ReadUntilSegment

Deprecated since version 4.00 of the module. This command will create a new EDI message and lock system tables. We recommend to use the commands SkipSegments in combination with RUNASYNC instead.

RUN

Deprecated since version 4.00 of the module. Please use RUNASYNC instead, if possible. The RUN command will lock EDI system tables and prevent multiple EDI processes at the same time.

Converter Functions

The X12 converter provides the object with the name X12 which provides the special function SEGMENTCOUNT that you can use to output the number of segments in the current X12 message. This value is typically used in the segment SE for the data element with the function: Total number of segments included in a transaction set.

Import / Export

We will discuss the properties and features for imports and exports separately.

Importing X12 Data

Import Mapping Header Properties

Direction

To import X12 data into Microsoft Dynamics 365 Business Central please select the property value Import.

Sample Search Depth

You can define that the assistant to create a new mapping should search for multiple interpretations of the data structure. Setting this property to a value higher than one will result in multiple candidates and longer analysis time during the execution of the mapping creation wizard.

Element Separator

The character to be used to separate elements. You can either directly enter the character or use a special character.

Subelement Separator

The character to be used to separate subelements. You can either directly enter the character or use a special character.

Segment Terminator

The character to be used to terminate a segment. You can either directly enter the character or use a special character.

Import Loops / Group

The X12 structure contains groups, which you can’t see from the actual data. These groups are defined in the documentation and allow you to repeat structures. Groups can be used, like any other loop to add, for example, tables.

If you add a table in write mode on an X12 import, the converter will check the child structures whether all mandatory elements are present and whether all filters are fulfilled. This is useful to add conditional branches in the mapping. On the other hand, it can make troubleshooting more difficult because the mapping can skip parts.

We recommend setting the property Min. Repeat to at least one, if you expect the structure to be present in the file. This way the module does not need to check the child structure and can directly try to convert the lines. This will make the mapping a little bit faster and also gives you better error messages in case the mapping structure does not match the file.

You can also use the loops without adding a table. On imports they will behave similar to a table in write mode and check the child structure before entering the loop. You can use this if you do not want to import the data or if you’re only interested in the last values of the loop.

Import Mapping Data Line Properties

After creating an EDI mapping line, you can configure the properties.

Import Mapping Data Lines

We will only show the properties for EDI mapping lines with the Type property set to Data as the other properties behave like in any other mapping. There are multiple data line types.

X12 Data Type

This properties defines the type of data line, that you want to configure.

The available options will vary depending on the position you try to add the mapping line. Some data lines are only allowed as children of another type.

This list will show all available options for X12 imports:

Segment

A segment defines the kind of data that follows. In X12 segment names have usually up to three characters and define a basic function. A mapping line of type Segment specifies the segment identifier. The actual data is represented as child lines in the EDI mapping.

Composite

A composite consists of several subelements, which belong together. A composite is only visible in the file, if multiple subelements in the composite are used. The composite itself does not hold any data.

DataElement

The data element is the structure that contains the actual data, which you can map to fields.

Import Segment

You need to define the segments, that can be in the file. If you want to parse the data, you’ll also have to add the composites and data elements, which you want to process. A segment can be conditional, meaning it might be in the file, but don’t have to be there.

Agency

This property can be used to specify the agency responsible for the X12 standard that is used. This is optional.

Version

This property can be used to specify the X12 version that is used. This is optional.

Message Type

This property can be used to specify the X12 message type that is used. This is optional.

Mandatory

Specifies whether an element has to be in the file or whether it is optional.

Mandatory

The element has to be in the file. If this mapping line is a children of a loop it might also be used as an acceptance criteria, whether the loop can be processed or not, like described above.

Conditional

The element is conditional. Do not create an error if it is not in the file. This element does not affect the acceptance of an loop.

Position

Specifies the position of the segment according to the documentation. This property is only used for reference and on new lines to find the correct segment. The property is ignored during the import of a file.

Spec. Max. Repeat

Defines how often the element might be repeated according to the documentation. This does not affect the import of the file, you have to add a loop or duplicate the line, if you want to process multiple instances.

Tag

Defines the segment tag. The segment tag is the value that appears in the file, typically up to three characters long, like “ST”, “SE” etc.

Name

The name is currently not used and for reference only.

Import Composite

Agency

This property can be used to specify the agency responsible for the X12 standard that is used. This is optional.

Version

This property can be used to specify the X12 version that is used. This is optional.

Mandatory

Specifies whether the composite has to be in the segment or whether it is optional.

Mandatory

The composite has to be in the segment. It might also be used as an acceptance criteria for the parent segment.

Conditional

The composite is conditional. Do not create an error if it is not in the file. This element does not affect the acceptance of an loop.

Position

Specifies the position of the composite according to the documentation, typically multiplied by 10. The position is typically a number, like “010”. The number has to be divisible by 10. The same position can only be read once. The position property can also change the position of the mapping line.

Tag

Defines the tag of the composite. The tag does not affect the processing of files. It is mainly used to automatically determine whether the element is mandatory according to the standard etc.

Name

The name is currently not used and for reference only.

Import DataElement

Agency

This property can be used to specify the agency responsible for the X12 standard that is used. This is optional.

Version

This property can be used to specify the X12 version that is used. This is optional.

DestExpr

Specifies the target of the data. We have a separate section on the destination expression. You can leave the destination expression type blank, if you do not want to process the data, but might want to at a later point. You can delete the mapping line, if you do not want to process the data.

You can use filters to define acceptance criterias, which will either not process a part of the mapping or create an error, if the data does not match the filter. Especially for X12 we highly recommend to use filters, whenever you take combined values with a qualifier to check that the qualifier is the expected one.

Mandatory

Specifies whether the data element has to be in the segment/composite or whether it is optional.

Mandatory

The data element has to be in the segment/composite. It might also be used as an acceptance criteria for the parent segment.

Conditional

The data element is conditional. Do not create an error if it is not in the file. This element does not affect the acceptance of an loop.

Position

Specifies the position of the data element according to the documentation, typically multiplied by 10. The position is typically a number, like “010”. The number has to be divisible by 10. The same position can only be read once. The position property can also change the position of the mapping line.

Tag

Defines the tag of the data element. The tag does not affect the processing of files. It is mainly used to automatically determine whether the element is mandatory according to the standard etc.

Name

The name is currently not used and for reference only.

Spec. Data Type

This property defines the data type according to the X12 standard. This is for information only and does not affect the processing.

Incorrect Length

The following values are allowed:

Ignore

Do not check the length of the output.

Max (Error)

Create an error if the value is longer than allowed.

Max (Truncate with Warning)

Create a warning if the value is longer than allowed and truncate the output to the allowed length.

Max (Truncate)

Truncate the value, is it is longer than allowed.

Max (Truncate…)

Truncate the value, is it is longer than allowed and add “…” at the end to show that the value is not complete.

Exact (Error)

Create an error if the output does not have the specified length.

Exact (Truncate/Pad with Warning)

Truncate or pad the value, if it has not the specified length and create a warning.

Exact (Pad)

Create an error if the value is longer than allowed. Pad the value if it is to short.

Exact (Truncate/Pad)

Truncate or pad the value to the given number of characters.

Spec. Length Type

This property defines whether the field is variable or fixed length according to the X12 standard. This is for information only and does not affect the processing.

Max. length

The field is variable length.

Exact length

The field has a fixed-length.

Length

Defines how many characters are allowed in the data element.

Format Type

You can select the data type of the data that you want to import.

The following values are available:

Auto

The field is automatically interpreted, based on the target data type.

Date

The data is interpreted as a date. You can specify the format with the property Format String.

Time

The data is interpreted as time information. You can specify the format with the property Format String.

Date/Time

The data is interpreted as date/time information. You can specify the format with the property Format String.

Format String

Only available, if the property Format Type is set. Specifies the date/time format string, like described in working with date/time format strings.

Sample Values

You can maintain a list of example values. The mapping creation/update wizard will fill this list automatically from the example file.

Exporting X12 Data

Export Mapping Header Properties

Direction

To export X12 data from Microsoft Dynamics 365 Business Central please select the property value Export.

Sample Search Depth

You can define that the assistant to create a new mapping should search for multiple interpretations of the data structure. Setting this property to a value higher than one will result in multiple candidates and longer analysis time during the execution of the mapping creation wizard.

Element Separator

The character to be used to separate elements. You can either directly enter the character or use a special character.

Subelement Separator

The character to be used to separate subelements. You can either directly enter the character or use a special character.

Segment Terminator

The character to be used to terminate a segment. You can either directly enter the character or use a special character.

Line Breaks

X12 files can have line breaks after each segment. This will make the file slightly larger, but easier to read. This property defines whether the converter should output line breaks. This option cannot be changed dynamically, if one partner requires line breaks and another doesn’t you’ll have to create two separate mappings. The converter will use a Windows line break (carriage return and line feed).

Fallback Communication Channel

The communication channel that should be used, if not specified before by either another mapping, AL / C/AL code or by using the business transactions. This can be left blank starting with Anveo EDI Connect 4.00.

Send Channel After Convert

Configures whether the communication channel should be send after running this mapping. This can be used to automatically sent the files, without the need of a separate job.

Fallback Receiver Partner

You can specify a receiver partner that is used as a fallback, in case there is no partner specified before. The partner is used by some communication channels to select the recipient. And can be accessed inside the mapping to output, for example, an identification number of the partner.

Export Mapping Line Properties

After creating an EDI mapping line, you can configure the properties.

Export Mapping Data Lines

We will only show the properties for EDI mapping lines with the Type property set to Data as the other properties behave like in any other mapping. There are multiple data line types.

X12 Type

This properties defines the type of data line, that you want to configure.

The available options will vary depending on the position you try to add the mapping line. Some data lines are only allowed as children of another type.

This list will show all available options for X12 imports:

Service String Advice

The line represent the special segment UNA, which is called service string advice. It is used to define, which control characters are used. From a technical point of view it is also mandatory to use non 7-bit characters in the file. Anveo EDI Connect will use the default characters, if not otherwise specified. If the segment UNA is in the file, you have to add this data line to the mapping to be able to import the file. This line will not create an error, if the file does not contain the segment. The actual control characters used are currently defined in the mapping. The

Segment

A segment defines the kind of data that follows. In X12 segment names have usually up to three characters and define a basic function. A mapping line of type Segment specifies the segment identifier. The actual data is represented as child lines in the EDI mapping.

Composite

A composite combines several data elements, which belong together. A composite is only visible in the file, if multiple data elements in the composite are used. The composite itself does not hold any data.

DataElement

The data element is the structure that contains the actual data, which you can map to fields.

Export Service String Advice

If you add a “Service String Advice” (UNA) to an EDI export mapping, you can configure the characters used in the output file. The UNA segment should be the first data line in the EDI mapping.

Component Element Separator

The separation character used between data elements of a composite.

Element Separator

The separation character used between data elements outside a composite.

Decimal Notation

The character used as a decimal point.

Release Indicator

A character that can be used to specify that the following character has to be interpreted as a literal and not as a control character.

Repetition Separator

A character that specifies a repetition of a data element. Anveo EDI Connect does not support repeated data elements at the moment, but you can define, which character is used in the output of the “Service String Advice”. Also setting this value will escape the repetition character in data outputs automatically.

Segment Terminator

The segment terminator, which will terminate the segment. Or in other word, this character is used to separate different segments. You can specify whether to use additional line breaks in the mapping header properties.

Export Segment

Only segments defined in the mapping can be outputted. So you have to configure all segments required in the output file.

Agency

This property can be used to specify the agency responsible for the X12 standard that is used. This is optional. This property does not affect the converter output.

Version

This property can be used to specify the X12 version that is used. This is optional. This property does not affect the converter output.

Message Type

This property can be used to specify the X12 message type that is used. This is optional. This property does not affect the converter output.

Conditional Output

You can set this property to the value True to only output the element if a specified source expression matches a specified filter.

NAV Filter

This property is only available if the property Conditional Output is set to True. A filter to check the SourceExpr against. The source expression will be interpreted as text for applying the filter. The element will only show up in the output, if the value from the specified source expression is within the specified filter.

SourceExpr

This property is only available if the property Conditional Output is set to True. This property specifies which value should be used to decide whether it matches the given filter and the element should appear in the output, or not.

Mandatory

Specifies whether an element has to be in the file or whether it is optional.

Mandatory

The element has to be in the file. This field is on exports for information only. The converter cannot detect missing mandatory elements.

Conditional

The element is conditional.

Position

Specifies the position of the segment according to the X12 documentation. This property is only used for reference and on new lines to find the correct segment. The property does not affect the converter output.

Spec. Max. Repeat

Defines how often the element might be repeated according to the documentation. This does not affect the converter output and is not checked during the output.

Tag

Defines the segment tag. The segment tag is the value that appears in the file, typically up to three characters long, like “ST”, “SE” etc.

Name

The name is currently not used and for reference only.

Export Composite

Agency

This property can be used to specify the agency responsible for the X12 standard that is used. This is optional. This does not affect the converter output.

Version

This property can be used to specify the X12 version that is used. This is optional. This does not affect the converter output.

Conditional Output

You can set this property to the value True to only output the element if a specified source expression matches a specified filter.

NAV Filter

This property is only available if the property Conditional Output is set to True. A filter to check the SourceExpr against. The source expression will be interpreted as text for applying the filter. The element will only show up in the output, if the value from the specified source expression is within the specified filter.

SourceExpr

This property is only available if the property Conditional Output is set to True. This property specifies which value should be used to decide whether it matches the given filter and the element should appear in the output, or not.

Mandatory

Specifies whether the composite has to be in the segment or whether it is optional.

Mandatory

The composite has to be in the segment. This property is for information only and does not affect the converter output.

Conditional

The composite is conditional.

Position

Specifies the position of the composite according to the documentation, typically multiplied by 10. This property is important, as it also defines how to output the information in the file. The position is typically a number, like “010”. The number has to be divisible by 10. The same position can only be written once. The position property can also change the position of the mapping line.

Tag

Defines the tag of the composite. The tag does not affect the processing of files. It is mainly used to automatically determine whether the element is mandatory according to the standard etc.

Name

The name is currently not used and for reference only.

Export DataElement

Agency

This property can be used to specify the agency responsible for the X12 standard that is used. This is optional. This property does not affect the output in the file.

Version

This property can be used to specify the X12 version that is used. This is optional. This property does not affect the output in the file.

SourceExpr

Specifies the source of the data to be written. We have a separate section on the source expression property.

Conditional Output

You can set this property to the value True to only output the element if a specified source expression matches a specified filter.

NAV Filter

This property is only available if the property Conditional Output is set to True. A filter to check the SourceExpr against. The source expression will be interpreted as text for applying the filter. The element will only show up in the output, if the value from the specified source expression is within the specified filter.

SourceExpr

This property is only available if the property Conditional Output is set to True. This property specifies which value should be used to decide whether it matches the given filter and the element should appear in the output, or not.

Mandatory

Specifies whether the data element has to be in the segment/composite or whether it is optional.

Mandatory

The data element has to be in the segment/composite. Setting an element to mandatory will result in generating the output, even if the value is empty. This can result in invalid files, as mandatory elements should always have a value. The converter will not create an error in this case. You should check that the required information for the export is present by using a check mapping.

Conditional

The data element is conditional.

Position

Specifies the position of the data element according to the documentation, typically multiplied by 10. The position is important for the converter to decide where to output the information. The position is typically a number, like “010”. The number has to be divisible by 10. The same position can only be written once. The position property can also change the position of the mapping line.

Tag

Defines the tag of the data element. The tag does not affect the processing of files. It is mainly used to automatically determine whether the element is mandatory according to the standard etc.

Name

The name is currently not used and for reference only.

Spec. Data Type

This property defines the data type according to the X12 standard. This is for information only and does not affect the processing.

Incorrect Length

The following values are allowed:

Ignore

Do not check the length of the output.

Max (Error)

Create an error if the value is longer than allowed.

Max (Truncate with Warning)

Create a warning if the value is longer than allowed and truncate the output to the allowed length.

Max (Truncate)

Truncate the value, is it is longer than allowed.

Max (Truncate…)

Truncate the value, is it is longer than allowed and add “…” at the end to show that the value is not complete.

Exact (Error)

Create an error if the output does not have the specified length.

Exact (Truncate/Pad with Warning)

Truncate or pad the value, if it has not the specified length and create a warning.

Exact (Pad)

Create an error if the value is longer than allowed. Pad the value if it is to short.

Exact (Truncate/Pad)

Truncate or pad the value to the given number of characters.

Spec. Length Type

This property defines whether the field is variable or fixed length according to the X12 standard. This is for information only and does not affect the processing.

Max. length

The field is variable length.

Exact length

The field has a fixed-length.

Length

Defines how many characters are allowed in the data element.

Format Type

You can select the data type of the data that you want to import.

The following values are available:

Auto

The field is automatically formatted, based on the source data type.

Text

The field is formatted as text.

Date/Time

A date/time information. The format can be specified by a qualifier that represents the allowed DTM qualifiers from the X12 standard. You can use the other Date and Date/Time formats, if you want to specify the format in another way.

Date/Time Format

The data is formatted as a date and time information. You can specify the format with the property Format String.

Date Format

The data is formatted as date information. You can specify the format with the property Format String.

Number

The data is formatted as a numeric value.

Format Qualifier

Only available, if the property Format Type is set to Date/Time.

You can use the lookup to see all available formats. The numbers are equal to the X12 format qualifier for DTM fields.

Format String

Only available, if the property Format Type is se to Date/Time Format or Date format format string.

If the property Format Type is set to NAV Format String, you can enter the format string, like described in the AL / C/AL help.

If set to date/time you can enter a format string, like described in working with date/time format strings.

Blank Zeros

Only available, if the property Format Type is set to Number. If available, specifies that empty values should be outputted as an empty field instead of the default empty representation.

Decimal Character

Only available, if the property Format Type is set to Number. Specifies which character should be used as a decimal separator. For X12 you should probably not change the value.

Thousands Separator Character

Only available, if the property Format Type is set to Number. Whether thousands should be separated and if, which character should be used. For X12 you should probably not change the value.

Max. Decimal Places

Only available, if the property Format Type is set to Number. The maximal count of decimal places that should be outputted.

Min. Decimal Places

Only available, if the property Format Type is set to Number. The minimal count of decimal places that should be in the output. This will automatically fill the missing places with zeros.

Sign

Only available, if the property Format Type is set to Number. Whether to output the positive/negative sign.

Negative Only

Only output the “-” sign.

Always

Output the “+” and “-” sign.

Sign after Value

Only available, if the property Format Type is set to Number. Whether to put the sign after the numbers. For X12 you should probably not change the value and leave it at the default value.

Sample Values

You can maintain a list of example values. The mapping creation/update wizard will fill this list automatically from the example file.