Config / Mappings / The XML Converter

The XML Converter

The XML converter can be used to import and export XML files. Anveo EDI Connect supports most XML features.

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

Using the Assistant

You can create the mapping structure from either an XML example file or an XSD file.

If you’re using an XML example file, please keep in mind that there is no way for the module to detect loops inside the XML structure. You should ensure that there is only one repetition of each looped structure or you’ll have to remove some of the created EDI mapping lines, afterwards.

The XSD support is still experimental and we do not support all XSD options. We will show a list of errors after the import, but usually the basic structure should be created. If there are multiple possible root nodes the module will ask you which one should be used. If the files contains includes, we will ask for the additional XSD files. The module will not follow any references to external URLs.

Using Commands

The XML converter currently does not support commands.

Import/Export

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

Importing XML Data

After creating the mapping, the first thing you should do is to check whether the header properties are set correctly. Afterwards you can start creating mapping lines, either by using the wizard, like described above, or by adding them manually.

The XML converter does not support the use of filters inside of write table loops, to create a record only, if the expected data is provided. Also for write loops the module will only look at the first child mapping line, if it is mandatory and not in the file the loop will not create a record. Else the module will create a record and try to process all other child lines as well.

Import Header Properties

Direction

To import XML data from an external source into Microsoft Dynamics 365 Business Central, set the property Direction to the value Import.

Ignore Unknown Elements

This property defines, how to handle situations, where the file contains elements, which are not defined in the mapping. The default value False will throw an error on unexpected data, which is strongly recommended. Setting the property value to False will ignore all elements, which are not defined in the mapping. This can also result in not parsing elements, which are defined in the mapping, because the mapping cannot detect them anymore. Use this with property with caution.

Default Namespace (URI)

This property defines a namespace that can be used on elements, by setting the mapping line namespace attribute to Default. Usually you’ll leave this property blank.

Import Line Properties

After creating an EDI mapping line, you can configure the properties. 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. The XML converter supports several data lines with different properties. You control what kind of XML mapping line you create, by setting the property Subtype:

Subtype

The subtype defines, what kind of data line you want to add. The following values are allowed:

Element

This mapping line represents a XML element. A XML element begins in the file with “<elementName>”.

Attribute

This mapping line represents a XML attribute. A XML attribute is inside the opening element tag: “<elementName attributeName=value>”.

Content

This line represents the content between an opening and closing element tag. The value is stored between: “<elementName>Content</elementName>”.

Comment

Lines of these type are for information only. The module does not support importing comments.

Indent

In the XML mapping we try to represent two different trees, one that groups all repeating structures in loops and one that represents the tree structure of XML. Often times this doesn’t conflict, but sometimes it can be ambiguous. For that reason there is a property with the name Ident which allows you to set the indentation of the XML structure explicitly. This is filled automatically from the import assistant, but you should set it manually, if you create mapping lines by hand.


XML Element on Imports

The following properties are only supported if the property Type is set to Data and the property Subtype is set to the value Element.

Prefix

XML allows you to reuse the same element name multiple times. Sometimes you want to show, to which structure the element belongs. You can specify a prefix that is used before the element name. This will result in representing the element as “<prefix:elementName>”. On imports this property is used only to make the mapping more readable. Since version 4.00 of the module the next property with the name Namespace (URI) is used to check whether the imported element is matching the mapping line.

Namespace (URI)

An element in a XML file can be assigned to a specific namespace. In the actual XML data this is represented by using prefixes before the element name and assigning the namespace URL to the prefix somewhere in the structure before or on the element. Since version 4.00 of the module, we’ll check whether the namespace in the file matches this value. If you don’t use namespaces on an element, leave this property blank.

Name

This property specifies the element name. The element name is used between the brackets.

Mandatory

Specifies whether this element is mandatory. Setting this property to the value True means that the element has to be in the file, or if there is a parent loop in write mode that the record is only created, if the element is present. Is you set this property value to False the element is considered to be conditional.

XML Attribute on Imports

The following properties are only supported if the property Type is set to Data and the property Subtype is set to the value Attribute. The mapping line need to be a children of a mapping line where the property Type is set to Data and the property Subtype is set to the value Element.

The order of attributes is not important and ignored by the import. The same attribute name is only allowed once per element.

Name

Specifies the attribute name.

DestExpr

Specifies where the data should be stored. In the XML converter filters will create an error, if the value does not match and cannot be used to conditionally process parts of the mapping.

There is a section on destination expressions, where you can learn more about this property.

Format Type

Specifies how the data should be interpreted by the module.

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.

Length Type

Specifies whether the value has to be of a certain length.

Length Type

You can specify that you want to check the length of incoming data. The following values are allowed:

Ignore

Do not check the length of the input.

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.

Length

This property is only available, if the property Length Type is set. The allowed length for the field.

XML Content on Imports

The following properties are only supported if the property Type is set to Data and the property Subtype is set to the value Content.

The mapping line need to be a children of a mapping line where the property Type is set to Data and the property Subtype is set to the value Element. If you have both XML attributes and a content, the order of the mapping lines is not important. We recommend putting the attributes in front for readability though.

DestExpr

Specifies where the data should be stored. In the XML converter filters will create an error, if the value does not match and cannot be used to conditionally process parts of the mapping.

There is a section on destination expressions, where you can learn more about this property.

Format Type

Specifies how the data should be interpreted by the module.

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.

Length Type

Specifies whether the value has to be of a certain length.

Length Type

You can specify that you want to check the length of incoming data. The following values are allowed:

Ignore

Do not check the length of the input.

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.

Length

This property is only available, if the property Length Type is set. The allowed length for the field.

XML Comment on Imports

The XML import does not handle XML comments. The converter will ignore any comments in the file. You can add lines of type comment, for reference reasons, but they do not provide any functionality or EDI properties for XML imports.

Exporting XML Data

Export Header Properties

Direction

To export XML data from Microsoft Dynamics 365 Business Central, set the property Direction to the value Export.

Default Namespace (URI)

The namespace that should be used, if the namespace property on an element is set to the text “Default“.

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 Line Properties

After creating an EDI mapping line, you can configure the properties. 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. The XML converter supports several data lines with different properties. You control what kind of XML mapping line you create, by setting the property Subtype:

Subtype

The subtype defines, what kind of data line you want to add. The following values are allowed:

Header

This mapping line represents a XML header. A XML header look like “<?xml … ?>”.

Element

This mapping line represents a XML element. A XML element begins in the file with “<elementName>”.

Attribute

This mapping line represents a XML attribute. A XML attribute is inside the opening element tag: “<elementName attributeName=value>”.

Content

This line represents the content between an opening and closing element tag. The value is stored between: “<elementName>Content</elementName>”.

Comment

Lines of these type are for information only. The module does not support importing comments.

DOCTYPE

Adds a doctype node to the output. A doctype look like “<!DOCTYPE … >”.

XML Header on Exports

Encoding

You can specify the XML encoding for the output. This will override the selected encoding from the header properties.

Standalone

Specifies whether the XML file is standalone.

Version

Specifies the XML version. As of now 1.0 is the only supported version.


XML Element on Exports

Prefix

XML allows you to reuse the same element name multiple times. Sometimes you want to show, to which structure the element belongs. You can specify a prefix that is used before the element name. The prefix and the namespace have to match. If the namespace is not explicitly defined with that prefix, the module will add the definition on the current element automatically.

Namespace (URI)

An element in a XML file can be assigned to a specific namespace. In the actual XML data this is represented by using prefixes before the element name and assigning the namespace URL to the prefix somewhere in the structure before or on the element.

Name

This property specifies the element name. The element name is used between the brackets.

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.

XML Attribute on Exports

Name

Specifies the XML attribute name.

Conditional Output

You can set this property to the value True to only output the XML attribute 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 XML attribute will only show up in the output, if the value from the specified source expression is within the specified filter.

SourceExpr

This is the documentation of the property SourceExpr of the conditional output. There is a second property with this name to specify the XML attribute value.

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 XML attribute should appear in the output, or not.

SourceExpr

This is the documentation of the property SourceExpr for the value of the XML attribute.

Specifies the source value for the attribute.

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.

NAV Format String

You can use a format string, like you can use for the Microsoft Dynamics 365 Business Central build-in AL / C/AL function FORMAT.

Date

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

Time

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

Date/Time

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

Number

The data is formatted as a numeric value.

Format String

Only available, if the property Format Type is se to date/time or NAV 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

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.

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.

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.

Length Type

This field is only available, if the property Field Type is set to Variable. The possible actions are shared between converters, in this converter you can use a different field type
for fixed-length fields. 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.

Length

This property can be used to specify the desired length of the output.

Alignment

This field is only available, if the property Field Type is set to Fixed Length or
the property Length Validation is set to pad the output. Where the output should be aligned, if the value is shorter than the character count to output.

Auto

Align depending on the source expression data type.

Left

Left align the value. This means the value is outputted first and afterwards the padding character is used to fill the field.

Right

Start with the padding and output the value right aligned.

Pad Character

This field is only available, if the property Field Type is set to Fixed Length or the property Length Validation is set to pad the output. Which character should be used for padding, if the value is not long enough.

XML Content on Exports

Conditional Output

You can set this property to the value True to only output the content if a specified source expression matches a specified filter. In Anveo EDI Connect 4.00 and newer: If you do not output a content for an element, the element will be represented in the output as a self-closing XML element in the form “<elementName />”. If you output an empty content the converter will output the start and end element.

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 XML content will only show up in the output, if the value from the specified source expression is within the specified filter.

SourceExpr

This is the documentation of the property SourceExpr of the conditional output. There is a second property with this name to specify the XML content value.

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 content should appear in the output, or not.

SourceExpr

This is the documentation of the property SourceExpr for the value of the XML content.

Specifies the source value for the attribute.

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.

NAV Format String

You can use a format string, like you can use for the Microsoft Dynamics 365 Business Central build-in AL / C/AL function FORMAT.

Date

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

Time

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

Date/Time

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

Number

The data is formatted as a numeric value.

Format String

Only available, if the property Format Type is se to date/time or NAV 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

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.

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.

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.

Length Type

This field is only available, if the property Field Type is set to Variable. The possible actions are shared between converters, in this converter you can use a different field type
for fixed-length fields. 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.

Length

This property can be used to specify the desired length of the output.

Alignment

This field is only available, if the property Field Type is set to Fixed Length or
the property Length Validation is set to pad the output. Where the output should be aligned, if the value is shorter than the character count to output.

Auto

Align depending on the source expression data type.

Left

Left align the value. This means the value is outputted first and afterwards the padding character is used to fill the field.

Right

Start with the padding and output the value right aligned.

Pad Character

This field is only available, if the property Field Type is set to Fixed Length or the property Length Validation is set to pad the output. Which character should be used for padding, if the value is not long enough.

XML Comment on Exports

Conditional Output

You can set this property to the value True to only output the comment, 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 XML comment will only show up in the output, if the value from the specified source expression is within the specified filter.

SourceExpr

This is the documentation of the property SourceExpr of the conditional output. There is a second property with this name to specify the XML comment value.

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 XML comment should appear in the output, or not.

SourceExpr

This is the documentation of the property SourceExpr for the value of the XML comment.

Specifies the source value for the attribute.

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.

NAV Format String

You can use a format string, like you can use for the Microsoft Dynamics 365 Business Central build-in AL / C/AL function FORMAT.

Date

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

Time

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

Date/Time

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

Number

The data is formatted as a numeric value.

Format String

Only available, if the property Format Type is se to date/time or NAV 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

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.

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.

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.

XML DOCTYPE on Exports

Conditional Output

You can set this property to the value True to only output the comment, 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 XML
DOCTYPE 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 XML DOCTYPE should appear in the output, or not.

Name

Specifies the DOCTYPE name, like “html”.

Public ID

Specifies the public ID.

System ID

Specifies the System ID.

Internal Subset

Specifies the internal subset.