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:
This command will leave the current mapping, without writing the current table record. Use with caution.
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.
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.
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.
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.
The ISA Segment
The X12 ISA (Interchange Control Header) segment is the first segment in an X12 EDI (Electronic Data Interchange) transaction set. It serves as a header for the entire transaction set and provides control information that identifies the sender and receiver of the transaction set, as well as the type of EDI transmission.
If you add the ISA segment by hand, please make sure to set the field with of all data element to fixed length (truncate/pad) and use the provided field lengths. The ISA segment needs to be 106 characters in total. The components of the ISA segment and their length in characters are:
Authorization Information Qualifier (2)
Authorization Information (10)
Security Information Qualifier (2)
Security Information (10)
Interchange ID Qualifier (2)
Interchange Sender ID (15)
Interchange ID Qualifier (2)
Interchange Receiver ID (15)
Interchange Date (6)
Interchange Time (4)
Interchange Control Standards Identifier (1)
Interchange Control Version Number (5)
Interchange Control Number (9)
Acknowledgment Requested (1)
Usage Indicator (1)
Component Element Separator (1)
To output this element, add a composite and name it ISA16. As children of that composite add two data elements and name them ISA16.1 and ISA16.2. For export both should have the source expression set to constant and and empty value. Both data element need to be marked as mandatory. This way the converter will only output the component element separator, which can be specified in the mapping header properties.
Import / Export
We will discuss the properties and features for imports and exports separately.
Importing X12 Data
Import Mapping Header Properties
To import X12 data into Microsoft Dynamics NAV 2013R2 please select the property value Import.
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.
The character to be used to separate elements. You can either directly enter the character or use a special character.
The character to be used to separate subelements. You can either directly enter the character or use a special character.
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.
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:
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.
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.
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.
This property can be used to specify the agency responsible for the X12 standard that is used. This is optional.
This property can be used to specify the X12 version that is used. This is optional.
This property can be used to specify the X12 message type that is used. This is optional.
Specifies whether an element has to be in the file or whether it is optional.
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.
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.
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.
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.
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.
The name is currently not used and for reference only.
Import Composite
This property can be used to specify the agency responsible for the X12 standard that is used. This is optional.
This property can be used to specify the X12 version that is used. This is optional.
Specifies whether the composite has to be in the segment or whether it is optional.
The composite has to be in the segment. It might also be used as an acceptance criteria for the parent segment.
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.
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.
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.
The name is currently not used and for reference only.
Import DataElement
This property can be used to specify the agency responsible for the X12 standard that is used. This is optional.
This property can be used to specify the X12 version that is used. This is optional.
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 criteria, 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.
Specifies whether the data element has to be in the segment/composite or whether it is optional.
The data element has to be in the segment/composite. It might also be used as an acceptance criteria for the parent segment.
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.
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.
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.
The name is currently not used and for reference only.
This property defines the data type according to the X12 standard. This is for information only and does not affect the processing.
The following values are allowed:
Do not check the length of the output.
Create an error if the value is longer than allowed.
Create a warning if the value is longer than allowed and truncate the output to the allowed length.
Truncate the value, is it is longer than allowed.
Truncate the value, is it is longer than allowed and add “…” at the end to show that the value is not complete.
Create an error if the output does not have the specified length.
Truncate or pad the value, if it has not the specified length and create a warning.
Create an error if the value is longer than allowed. Pad the value if it is to short.
Truncate or pad the value to the given number of characters.
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.
The field is variable length.
The field has a fixed-length.
Defines how many characters are allowed in the data element.
You can select the data type of the data that you want to import.
The following values are available:
The field is automatically interpreted, based on the target data type.
The data is interpreted as a date. You can specify the format with the property Format String.
The data is interpreted as time information. You can specify the format with the property Format String.
The data is interpreted as date/time information. You can specify the format with the property 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.
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
To export X12 data from Microsoft Dynamics NAV 2013R2 please select the property value Export.
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.
The character to be used to separate elements. You can either directly enter the character or use a special character.
The character to be used to separate subelements. You can either directly enter the character or use a special character.
The character to be used to terminate a segment. You can either directly enter the character or use a special character.
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).
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.
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.
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.
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:
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.
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.
The data element is the structure that contains the actual data, which you can map to fields.
Export Segment
Only segments defined in the mapping can be outputted. So you have to configure all segments required in the output file.
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.
This property can be used to specify the X12 version that is used. This is optional. This property does not affect the converter output.
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.
You can set this property to the value True to only output the element if a specified source expression matches a specified 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.
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.
Specifies whether an element has to be in the file or whether it is optional.
The element has to be in the file. This field is on exports for information only. The converter cannot detect missing mandatory elements.
The element is conditional.
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.
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.
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.
The name is currently not used and for reference only.
Export Composite
A lot of X12 message types do not require composites
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.
This property can be used to specify the X12 version that is used. This is optional. This does not affect the converter output.
You can set this property to the value True to only output the element if a specified source expression matches a specified 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.
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.
Specifies whether the composite has to be in the segment or whether it is optional.
The composite has to be in the segment. This property is for information only and does not affect the converter output.
The composite is conditional.
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.
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.
The name is currently not used and for reference only.
Export DataElement
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.
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.
Specifies the source of the data to be written. We have a separate section on the source expression property.
You can set this property to the value True to only output the element if a specified source expression matches a specified 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.
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.
Specifies whether the data element has to be in the segment/composite or whether it is optional.
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.
The data element is conditional.
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.
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.
The name is currently not used and for reference only.
This property defines the data type according to the X12 standard. This is for information only and does not affect the processing.
The following values are allowed:
Do not check the length of the output.
Create an error if the value is longer than allowed.
Create a warning if the value is longer than allowed and truncate the output to the allowed length.
Truncate the value, is it is longer than allowed.
Truncate the value, is it is longer than allowed and add “…” at the end to show that the value is not complete.
Create an error if the output does not have the specified length.
Truncate or pad the value, if it has not the specified length and create a warning.
Create an error if the value is longer than allowed. Pad the value if it is to short.
Truncate or pad the value to the given number of characters.
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.
The field is variable length.
The field has a fixed-length.
Defines how many characters are allowed in the data element.
You can select the data type of the data that you want to import.
The following values are available:
The field is automatically formatted, based on the source data type.
The field is formatted as text.
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.
The data is formatted as a date and time information. You can specify the format with the property Format String.
The data is formatted as date information. You can specify the format with the property Format String.
The data is formatted as a numeric value.
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.
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.
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.
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.
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.
Only available, if the property Format Type is set to Number. The maximal count of decimal places that should be outputted.
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.
Only available, if the property Format Type is set to Number. Whether to output the positive/negative sign.
Only output the “-” sign.
Output the “+” and “-” sign.
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.
You can maintain a list of example values. The mapping creation/update wizard will fill this list automatically from the example file.