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
  • M3StandardFormatVersion (mandatory), always set to 1.
  • ReportLayout (mandatory), Report layout used.
  • DocumentDivision (mandatory), Division for document (not division for user running output function).
  • CountryVersion (mandatory), Country version from (MNS100/L) based on documentDivision.
  • BaseCountry (mandatory), Country of the division generating the document. Usually, the country of the Document division, the only exception is if fiscal representation is used.
  • FromToCountry (mandatory), Country code for the receiver of the document. Based on User, Customer, or Supplier. Based on (CRS045).
  • DocumentLanguage (mandatory), Language code for the receiver of the document. Based on user, customer, or supplier. Based on 'Language. Open' (CRS010). Custom languages created in 'System Language. Open' (MNS105) may be used as document language in (CRS010). See details in M3 Application Foundation > System Administration > Custom Languages.
  • Locale (mandatory), settings in format xx-yy. xx is the ISO code for language (CRS010) based on DocumentLanguage. yy is ISO code for country (CRS045) based on FromToCountry. Used to format dates and decimals.
    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 (mandatory), Date format for document based on user or customer/supplier (from M3 BE settings). We recommend that you use the 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 (mandatory), decimal format for document based on user or customer/supplier (from BE settings). We recommend that you use the locale settings for formatting of decimal instead of this field.
  • ThousandSeparator (mandatory), 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>
  • M3OutDocument (mandatory), root node, always M3OutDocument for Format 1 – M3 standard document.
  • Metadata (mandatory), general information about the XML file.
  • DataArea (mandatory), includes all data in the XML file. The DataArea includes one or many Documents.
  • Document (mandatory), can be 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 (optional), selection and filter fields. Always single occurrence.
  • Formatting (mandatory for format 1), information of how data should be formatted.
  • Header (mandatory), data for repeating information on top of a layout.
  • Footer (mandatory), data for repeating information on bottom of a layout.
  • DocumentHeader (optional), Document header information.
  • iTextBlock (optional).
  • SubDocument (mandatory), if document is split into sub-documents. Usually single.
  • TextBlock (optional).
  • Lines (optional), groups all lines.
  • TextBlock (optional).
  • TextBlock (optional).
  • DocumentTotal (optional).
  • Media (mandatory for format 1), information for distribution of the printout.

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>
  • M3OutReport (mandatory), root node, always M3OutReport
  • Metadata (mandatory), general information about the XML file.
  • DataArea (mandatory), includes all data in the XML file. The DataArea includes one or many report.
  • Report (mandatory), normally single occurrence.

Report

<Report>
<Cover>
<Formatting>
<Header>
<Subreport>
<Media>
</Report>
  • Cover (optional), selection and filter fields. Always single occurrence.
  • Formatting (mandatory), information of how data should be formatted.
  • Header (mandatory), data for repeating information on top of a layout
  • Subreport (mandatory). if report is split into sub-reports. Normally single occurrence
  • Media (mandatory), 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