Design and Structure of XML File

This document explains the design and structure of the XML file. Two different standards are available depending on the format selected in 'XML Structure. Open' (CMS006).

Common standards are used for all formats.

Data type Decimal

Data with Data type Decimal are included in the XML according to these rules:

  • Without thousand separator
  • Decimal format, always period (.)
  • Rounded to correct number of decimals and adjusted per price quantity

    Example: 9999999.99

Metadata for how a decimal field should be formatted is included in the section Localization.

<DecimalFormat>,</DecimalFormat>
<ThousandSeparator>.<ThousandSeparator>
<Locale>en-GB<Locale>

We recommend that you use the locale settings for formatting of decimals.

Debit/Credit code

Whether Debit/Credit code should be used is indicated in Element DebitCreditCodeUsed (true/false), section DocumentInformation.

<DocumentInformation>
<DebitCreditCodeUsed>true</DebitCreditCodeUsed>

Currency amount fields that should use Debit/Credit code has an additional attribute "D-C" including the Debit/Credit code sign. 

<VFORTO D-C="D">68325.00</VFORTO>
<VFTOPY D-C="D">68325.00</VFTOPY>

Data type date

Data with data type date are included in this format: YYYY-MM-DD.

  • [YYYY] indicates a four-digit year, [MM] indicates a two-digit month, [DD] indicates a two-digit day.
  • Each date value has a fixed number of digits that is padded with leading zeros.
  • The separator used between date values is the hyphen (-).

XML example without relation to time zone:

<UHIVDT>2016-03-21</UHIVDT>

XML example with relation to time zone:

If the date has a relation to a time zone is the offset from the UTC time added as positive or negative value behind the date. There is no need to use the UTC time offset when using the date on a document, it is only used if the date need to be converted to UTC time.

<UHIVDT>2016-03-21+5:00</UHIVDT>

Metadata for how a date field should be formatted is included in section localization:

<DateFormat>YYMMDD</DateFormat>
<DateEditing>/<DateEditing>
<Locale>en-GB<Locale>

We also recommend that you use the locale settings for formatting of dates.

Data type time

Data with data type time are included in the format hh:mm:ss

  • [hh] indicates the hour, [mm] indicates the minutes, [ss] indicates the seconds.
  • Each time value has a fixed number of digits that is padded with leading zeros.
  • The separator used between date values is (:).

XML example without relation to time zone:

14:05:23
<UHTIID>14:05:23</UHTIID>

XML example with relation to time zone:

If the date has a relation to a time zone is the offset from the UTC time added as positive or negative value behind the time. There is no need to use the UTC time offset when using the time on a document, it is only used if the time need to be converted to UTC time.

<UHTIID>14:05:23+5:00</UHTIID>

Formatting

Formatting is a section with metadata to help an external output management application for layout design.

<Formatting>
<M3StandardFormatVersion>1</M3StandardFormatVersion>
<ReportLayout>M3_STD_03-01</ReportLayout>
<Structure>M3_STD_03-01</Structure>
<PaperSize>A4</PaperSize>
<Localization>
<DocumentDivision>AAA</DocumentDivision>
<CountryVersion>GB</CountryVersion>
<BaseCountry>GB</BaseCountry>
<FromToCountry>GB</FromToCountry>
<DocumentLanguage>GB</DocumentLanguage>
<Locale>en-GB</Locale>
<DateFormat>YYMMDD</DateFormat>
<DecimalFormat>,</DecimalFormat>
<ThousandSeparator>.</ThousandSeparator>
/Localization>
<DocumentInformation>
</Formatting>

These are the required XML tags <Formatting> XML tag:

  • M3StandardFormatVersion is always set to 1.
  • ReportLayout is used in the report layout.
  • DocumentDivision is the division for document and not division for user running output function.
  • CountryVersion is the country version from (MNS100/L) based on documentDivision.
  • BaseCountry is the country of the division generating the document with the only exception if fiscal representation is used.
  • FromToCountry is the country code for the receiver of the document based on User, Customer, or Supplier, and is based on (CRS045).
  • DocumentLanguage is language code for the receiver of the document based on user, customer, or supplier, and is based on 'Language. Open' (CRS010). Custom languages created in 'System Language. Open' (MNS105) which is used as document language in (CRS010). See details in M3 Application Foundation > System Administration > Custom Languages.
  • Locale settings is in format xx-YY. Set a Locale manually in 'Country.Open' (CRS045). If Locale is not set manually, then xx is the ISO code for language (CRS010) based on DocumentLanguage. YY is ISO code for country (CRS045) based on FromToCountry. Locale is used to format dates and decimals.

    This table shows the settings for Locale:

    Language Country Locale
    M3 code ISO code M3 code ISO code
    GB en US US en-US
    GB en GB GB en-GB
    DE de DE DE de-DE
    SE sv SE SE sv-SE
  • DateFormat is the date format for document based on user, customer or supplier the from M3 BE settings. This table shows the recommended locale settings for formatting of dates instead of this field:
    BE setting for date format Text in element DateFormat
    YMD YYMMDD
    DMY DDMMY
    MDY MMDDYY
    YWD YYWWD
  • DecimalFormat is the decimal format for document based on user, customer or supplier from the M3 BE settings. We recommend that you use the locale settings for formatting of decimal instead of this field.
  • ThousandSeparator is always set to opposite separator from decimal format.

Format 1 – M3 standard document and 3 - Open

These are the most important standards for Format 1- M3 standard document:

  • Element name is equal to field name in the M3 Business Engine table. This makes it easy to identify the source if you know the M3 Database.
  • Labels included as attribute ’Label’. These are translated according to document language.
  • Codes with description grouped in sections sharing same label. For example, delivery terms and other terms texts. 
    M3OutDocument
<M3OutDocument>
	<Metadata> 
	<DataArea> 
		<Document>
<Document>
<Document>
</DataArea>
</M3OutDocument>
  • These are the XML tags for M3OutDocument XML tag:
    • M3OutDocument is a root node. Use M3OutDocument for Format 1 – M3 standard document.
    • Metadata is the general information about the XML file.
    • DataArea includes all data in the XML file. DataArea includes one or many Documents.
    • Document is either a single or multiple occurrence. Document is for example one Invoice, one Purchase order or, one Statement of account number.

      Document

      One Document is, for example, one Invoice or one Purchase order.

      <Document>
<Cover>
<Formatting/>
<Header/>
<Footer/>
<DocumentHeader/>
<TextBlock/>
<SubDocument/>
<TextBlock/>
<Lines/>
<TextBlock />
<TextBlock/>
<VATSummaryBox/>
<DocumentTotal/>
<Media/>
</Document>
    • Cover is selection and filter fields, and is always single occurrence. This XML tag is optional.
    • Formatting is the information of how data are formatted. Only mandatory for format 1
    • Header is the data for repeating information on top of a layout.
    • Footer is the data for repeating information on bottom of a layout.
    • DocumentHeader is the document header information.
    • iTextBlock is an optional XML tag.
    • SubDocument is when the document is split into sub-documents. This XML tag is usually single.
    • TextBlock is an optional XML tag.
    • Lines groups all lines.
    • TextBlock is an optional XML tag. This is the second TextBlock tag.
    • TextBlock is an optional XML tag. This is the third TextBlock tag.
    • DocumentTotal is an optional XML tag.
    • Media is the information for distribution of the printout. Only mandatory format 1.

For format 3 – Open, the sections Cover, Formatting or Media can be deactivated on (CMS025/E). Section Cover can be deactivated for both formats 1 and 2 on (CMS025/E).

DocumentHeader

DocumentHeader is information that is common for the Document. Within the Document is the Address section placed.

XML example with one address:

<DocumentHeader Label="Document header">
<UIIVNO Label="Invoice no">201401561</UIIVNO>
<OAORNO Label="CO no">1000025077</OAORNO>
<OAWHLO Label="Warehouse">110</OAWHLO>
<Address Label="Delivery Address Type="Delivery"> 
</DocumentHeader>

XML example with two addresses:

<DocumentHeader Label="Document header">
<UIIVNO Label="Invoice no">201401561</UIIVNO>
<OAORNO Label="CO no">1000025077</OAORNO>
<OAWHLO Label="Warehouse">110</OAWHLO>
<Address Label="Delivery Address Type="Delivery"> 
<Address Label="Payer Address Type="Payer">
</DocumentHeader>

Addresses are separated by types. The type is included as an attribute and can have these values:

Type Description
Delivery Delivery address
Customer Customer address
Payer Payer address
Invoice Invoice address
Supplier Supplier address
Payee Payee address
Company Company address
Location Location address
Quotation Quotation address
Bank Bank address

These elements are always included in an Address section:

  • CUNM - Name
  • ADR1 - Address line 1
  • ADR2 - Address line 2
  • ADR3 - Address line 3
  • ADR4 - Address line 4

XML example with one address:

<Address Label="Delivery Address Type="Delivery">
<VFCUNM>Infor company</ VFCUNM >
<VFADR1>Utterstreet</VFADR1>
<VFADR2>Number 4</VFADR2>
<VFADR3>187 Taby</VFADR3>
<VFADR4>Sweden</VFADR4>
</Address>

XML example with two addresses:

<Address Label="Delivery Address Type="Delivery">
<VFCUNM>Infor company</ VFCUNM>
<VFADR1>Utterstreet</VFADR1>
<VFADR2>Number 4</VFADR2>
<VFADR3>187 Taby</VFADR3>
<VFADR4>Sweden</VFADR4>
 </Address>
<Address Label="Payer Address Type="Payer">
<VFCUNM>Infor Sweden AB</ VFCUNM >
<VFADR1>Borgarfjordsgatan 9</VFADR1>
<VFADR2></VFADR2>
<VFADR3>164 40 Kista</VFADR3>
<VFADR4>Sweden</VFADR4>
 </Address

Text block is separated by types. The type is included as an attribute and can have these values:

Type Subtype
ExemptionText
DocumentText PreText or PostText
CustomerText PreText or PostText
OrderText PreText or PostText
OrderLineText PreText or PostText
ItemText PreText or PostText
CoreTerms
ConfigText
AssignmentText PreText or PostText
AgreementText PreText or PostText
GeneralText
AttributeText
FinReasonText

XML example with one text block:

<TextBlock Label="Document text" Type="DocumentText" SubType="PreText">
<BD-3>asldfjasljfalsjfaslfdj</BD-3>
<BD-3>hhdftdgsdfsfsfs</BD-3>
<BD-3>sdwe63gdfg34te</BD-3>
<BD-3>xxrwrwtey567</BD-3>
……
</TextBlock>

XML example with two text blocks:

<TextBlock Label="Document text" Type="DocumentText" SubType="PreText">
<BD-3>asldfjasljfalsjfaslfdj</BD-3>
<BD-3>hhdftdgsdfsfsfs</BD-3>
<BD-3>sdwe63gdfg34te</BD-3>
<BD-3>xxrwrwtey567</BD-3>
……
</TextBlock>
<TextBlock Label="Order text" Type="OrderText" SubType="PreText">
< BD-3>ddddfafj</BD-3>
< BD-3>dddddddddsss</BD-3>
< BD-3>4353333333</BD-3>
</TextBlock>

Line is repeating and grouped by lines.

Labels are only included once before any Line section.

In many cases, subtotal values (SublineValues) are included at the break of key fields and are used for sorting.

XML example with no subtotal values (Most simple example with only a list of one or many lines):

<Lines Label="Lines">
<UBPONR Label="Line"/>
<UBITNO Label="Item number"/>
<Line>
<UBPONR>1</UBPONR>
<UBITNO>MB_101</UBITNO>
</Line>
<Line>
<UBPONR>2</UBPONR>
<UBITNO>MB_202</UBITNO>
</Line>
<Line>
<UBPONR>3</UBPONR>
<UBITNO>MB_303</UBITNO>
</Line>
</Lines>

XML example with subtotal values (Example with subtotal values (SublineValues) included):

<Lines Label="Lines">
<UBPONR Label="Line"/>
<UBITNO Label="Item number"/>
	<Line>
<UBPONR>1</UBPONR>
<UBITNO>MB_101</UBITNO>
</Line>
<Line>
<UBPONR>2</UBPONR>
<UBITNO>MB_202</UBITNO>
		<SublineValues>
<Element 1/>
<Element 2/>
		</SublineValues>
<Line>
<UBPONR>3</UBPONR>
<UBITNO>MB_303</UBITNO>
</Line>
<Line>
<UBPONR>4</UBPONR>
<UBITNO>MB_404</UBITNO>
		<SublineValues>
<Element 1/>
<Element 2/>
		</SublineValues>
</Line>
</Lines>

XML example with sorting by address:

If lines are grouped by any other reason than subtotals, subline must also be used. Below are the lines sorted by address. Address information is then included per subline.

<Lines Label="Lines">
<UBPONR Label="Line"/>
<UBITNO Label="Item number"/>
	<Subline>
<Address Label="Delivery Address Type="Delivery">
	<Line>
<UBPONR>3</UBPONR>
<UBITNO>MB_303</UBITNO>
</Line>
</Subline>
	<Subline>
<Address Label="Delivery Address Type="Delivery">
<Line>
<UBPONR>4</UBPONR>
<UBITNO>MB_404</UBITNO>
</Line>
	<Line>
<UBPONR>5</UBPONR>
<UBITNO>MB_505</UBITNO>
</Line>
	</Subline>
</Lines>

XML example with Pre and Post text:

If Pre and Post text is used for the line, they should be placed within the line.

<Lines Label="Lines">
<UBPONR Label="Line"/>
<UBITNO Label="Item number"/>
<Line>
<UBPONR>3</UBPONR>
<UBITNO>MB_303</UBITNO>
<TextBlock Label="Item text" Type="ItemText" SubType="PreText">
<TextBlock Label="Item text" Type="ItemText" SubType="PostText">
</Line>
</Lines>

HeadCharges

  • Always Section HeadCharges
  • Charge is repeating and grouped by HeadCharges
  • Labels are only included once before any charge section

XML example with one charge:

<HeadCharges>
<USCRD0 Label="Description"/>
<USCRID Label="Charge"/>
<VFCHAM Label="Charge amount"/>
<VFVTCD Label="Vcd"/>
<Charge Label="Charge">
<USCRD0>Monica's Head charge_VATcd01</USCRD0>
<USCRID>MBHC1</USCRID>
<VFCHAM>200.00</VFCHAM>
<VFVTCD>1</VFVTCD>
</Charge>
</HeadCharges>

XML example with two charges:

<HeadCharges>
<USCRD0 Label="Description"/>
<USCRID Label="Charge"/>
<VFCHAM Label="Charge amount"/>
<VFVTCD Label="Vcd"/>
<Charge Label="Charge">
<USCRD0>Monica's Head charge_VATcd01</USCRD0>
<USCRID>MBHC1</USCRID>
<VFCHAM>200.00</VFCHAM>
<VFVTCD>1</VFVTCD>
</Charge>
<Charge Label="Charge">
<USCRD0>Monica's Head charge_VATcd03</USCRD0>
<USCRID>MBHC3</USCRID>
<VFCHAM>400.00</VFCHAM>
<VFVTCD>1</VFVTCD>
</Charge>
</HeadCharges>

DocumentTotal

  • Always Section type 022 – DocumentTotal
  • Always Level 03
  • Should include all elements that contains totals for the whole document.

Additional labels

  • Labels not related to any data are included as normal labels but with Element value true or false.
  • Additional labels are included first in a section.

Example 1

Text "***PRELIMINARY***" included in the DocumentHead

<DocumentHead Label="Document header">
<VFPREL Label="Preliminary">true</VFRELI>
…..
</DocumentHead>
<DocumentTotal Label="Document total">
<VFPLAC Label="Place">true</VFPLAC>
<VFDATE Label="Date">true</VFDATE>
<VFSIGN Label="Signature">true</VFSIGN>
…..
</DocumentTotal>

Example 2

Signature line with "Place", "Date" and "Signature" in DocumentTotal:

Place Date Signature

XML example

<DocumentTotal Label="Document total">
<VFPLAC Label="Place">true</VFPLAC>
<VFDATE Label="Date">true</VFDATE>
<VFSIGN Label="Signature">true</VFSIGN>
…..
</DocumentTotal>

Format 2 - M3 standard report

These are the most important standards for Format 2 - M3 standard report:

  • Element name is equal to field name in the M3 Business Engine table. This makes it easy to identify the source if you know the M3 Database.
  • Labels included as attribute "Label". These are translated according to document language.
  • Codes with description grouped in sections sharing same label. For example, delivery terms, and other terms texts.

M3OutReport

<M3OutReport>
	<Metadata> 
	<DataArea> 
		<Report>
<Report>
<Report>
</DataArea>
</M3OutReport>

These are the required XML tags for M3OutReport XML tag:

  • M3OutReport is a root node. Always use M3OutReport.
  • Metadata is the general information about the XML file.
  • DataArea includes all data in the XML file. The DataArea includes one or more reports.
  • Report is normally single occurrence.

Report

<Report>
<Cover>
<Formatting>
<Header>
<Subreport>
<Media>
</Report>

These are the required XML tags for Report XML tag:

  • Cover is selection and filter fields, and always single occurrence. This XML tag is optional.
  • Formatting is the information of how data is formatted.
  • Header is the data for repeating information on top of a layout.
  • Subreport is when a report is split into subreports. Subreport is normally a single occurrence.
  • Media is the information for distribution.

Section Cover to be deactivated on (CMS025/E).

Subreport

<Subreport>
<TableInformation Type="xx">
<TableInformation Type="yy">
<TableInformation Type="zz">
<Table Type="xx"
</Subreport>

Format 3 – Open

The most important standards for Format 3 - Open are:
  • Element name and Grp by element can be emptied.
  • Freely XML structure can be created.
<?xml version="1.0" encoding="UTF-8"?>
<M3FinancialReport>
<Grouping Section>
<Lines>
   <Grouping Section>
   <Custom>
   <Grouping Section>
   <Custom>

Free fields

Additional fields called 'Free fields' are defined in 'XML Structure. Open' (CMS006/H). Free fields enable you to build a search query for a layout in IDM Output Management. These fields are also used to set the attribute values in IDM.

Selection of free fields

To set free fields in (CMS006/H), you must first set up values in 'Document Type. Open' (MNS060/E).

These are the free fields defined on (MNS060/E):

  • 60 - Free field 1
  • 61 - FF02 - Free field 2
  • 62 - FF03 - Free field 3
  • 63 - FF04 - Free field 4
  • 64 - FF05 - Free field 5
  • 65 - FF06 - Free field 6
  • 66 - FF07 - Free field 7
  • 67 - FF08 - Free field 8
  • 68 - FF09 - Free field 9
  • 69 - FF010 - Free field 10
  • 70 - RGS655PF Report

Selected attribute value (60-69) on (MNS060/E) should correspond to the free fields on (CMS006/H).

Selected attribute value (70) on (MNS060/E) should correspond to the reports on (RGS600/E).

Related topics