XML is eXtensible Markup Language, a structured text format developed to describe data to be shared by dissimilar systems. XML has become a default standard for communications between systems. To make handling XML-formatted data simpler and more error resistant, NAV provides XMLports, a data import/export object. In addition to processing XML-formatted data, XMLports can also handle a wide variety of other text file formats (including CSV files, generic flat files, and so on). XML formatted data is text based, with each piece of information structured in one of two basic formats, Elements or Attributes. An Element is the overall logical unit of information while an Attribute is a property of an Element. They are formatted as follows:
<Tag>element value</Tag> (an Element format)
<Tag AttribName = "attribute data value">
(an Attribute format)Elements can be nested, but must not overlap. Element and Attribute names are case-sensitive. Names cannot start with a number, punctuation character, or the letters "xml" (or XML, and such). Also, they cannot contain spaces.
An Attribute value must always be enclosed in single or double quotation marks. Some references suggest that Elements should be used for data and Attributes for metadata. Complex data structures are built up of combinations of these two formats.
For example:
<Table Name='Sample XML format'> <Record> <DataItem1>12345</DataItem1> <DataItem2>23456</DataItem2> </Record> <Record> <DataItem1>987</DataItem1> </Record> <Record> <DataItem1>22233</DataItem1> <DataItem2>7766</DataItem2> </Record> </Table>
In this case, we have a set of data identified as a Table
with an attribute of Name equal to 'Sample
XML
format'
, which contains three Records
, each Record
containing data in one or two fields named DataItem1
and DataItem2
. The data is in a clearly structured text format so it can be read and processed by any system prepared to read this particular XML format. If the field tags are well designed, the data is easily interpretable by humans as well. The key to successful exchange of data using XML is the sharing and common interpretation of the format between the transmitter and the recipient.
XML is a standard format in the sense that the data structure options are clearly defined. But it is very flexible in the sense that the identifying tag names in < >
brackets and the related data structures that can be defined and handled are totally open-ended. The specific structure and the labels are whatever the communicating parties decide they should be. The "rules" of XML only determine how the basic syntax shall operate.
XML data structures can be as simple as a flat file consisting of a set of identically formatted records or as complex as a sales order structure with headers containing a variety of data items, combined with associated detail lines containing their own variety of data items. An XML data structure can be as complicated as the application requires.
XML standards are maintained by the W3C whose web site is http://www.w3.org/. There are many other useful web sites for basic XML information.
Although in theory XMLports can operate in both an import and an export mode, in practice, individual XMLport objects tend to be dedicated to either import or export. This allows the internal logic to be simpler. XMLports utilize a process of looping through and processing data similar to that of Report objects.
The components of XMLports are:
XMLport properties are shown in the following screenshot of the Properties of the XMLport object 9170:
Descriptions of the individual properties follow:
The TextEncoding option is only available if the Format property is Fixed Text or Variable Text. In this case, a character coding option of MS-DOS is available and is the default.
The XMLport has a very limited set of triggers, which are listed next:
An XMLport can contain any number of data lines. The data lines are laid out in a strict hierarchical structure, with the elements and attributes mapping exactly, one for one, in the order of the data fields in the external text file, the XML document.
XMLports should not be run directly from a Navigation Pane action command (due to conflicts with NAV UX standards), but can be run either from ribbon actions on a Role Center or other page, or by means of an object containing the necessary C/AL code. When running from another object (as opposed to running from an action menu entry), the C/AL code calls the XMLport to stream data either to or from an appropriately formatted file (XML document or other text format). This calling code is typically written in a Codeunit, but can be placed in any object that can contain the C/AL code.
The following example code executes an exporting XMLport and saves the resulting file from the NAV service tier to the client machine:
XMLfile.CREATE(TEMPORARYPATH + 'RadioShowExport.xml'), XMLfile.CREATEOUTSTREAM(OutStreamObj); XMLPORT.EXPORT(50000,OutStreamObj); FromFileName := XMLfile.NAME; ToFileName := 'RadioShowExport.xml'; XMLfile.CLOSE; //Need to call DOWNLOAD to move the xml file //from the service tier to the client machine DOWNLOAD(FromFileName,'Downloading File...','C:','Xml file(*.xml)|*.xml',ToFileName); //Make sure to clean up the temporary file from the //service tier ERASE(FromFileName);
Two text variables (the "from" file name and "to" file name), a file variable, and an OutStream object variable are required to support the preceding code. The data variables are defined as shown in the following screenshot:
The XMLport line properties which are active on a line depend on the contents of the SourceType property. The first four properties listed are common to all three SourceType values (Text, Table, and Field) and the other properties specific to each are listed below the screenshots showing all the properties for each SourceType.
The following screenshot shows the properties for SourceType as Text:
The description of the Text-specific properties is as follows:
The Width, MinOccurs, and MaxOccurs properties are discussed later in this chapter.
The following screenshot shows the properties for SourceType as Table:
The descriptions of the table-specific properties are as follows:
No
. If this property is set to Yes
, it allows the creation of a Temporary table in working storage. Data imported into this table can then be evaluated, edited, and manipulated before being written out to the database. This Temporary table has the same capabilities and limitations as a Temporary table defined as a Global variable.Yes
(the default), an imported record will be automatically saved to the table. Either AutoUpdate or AutoReplace must also be set to Yes
.The Width, MinOccurs, and MaxOccurs properties are discussed later in this chapter.
The following screenshot shows the properties for SourceType as Field:
The description of the Field-specific properties is as follows:
Yes
, then whenever the field is imported into the database, the OnValidate() trigger of the field will be executed.Yes
, the field will be calculated before it is retrieved from the database. Otherwise, a FlowField would export as an empty field.The details of the Width, MinOccurs, and MaxOccurs properties follow in the next section.
An Element data item may appear many times but an Attribute data item may only appear at most once; the occurrence control properties differ based on the NodeType.
The Element-specific properties are as follows:
Fixed Text
, then this field is used to define the fixed width of this element's field.Zero
or Once
(the default).Once
or Unbounded
. Unbounded
(the default) means any number of times.The XMLport line triggers are shown in the following screenshot for the three line Source types: Profiles (Text), Profile (Table), and ID (Field):
As we can see in the preceding screenshot, there are different XMLport triggers depending on whether DataType is Text
, Table
, or Field
.
The triggers for DataType as Text are:
The triggers for DataType as Table are as follows:
Yes
, to update the imported data before saving it.Yes
, to update the data after updating.The triggers for DataType as Field are as follows:
XMLports can also have a Request Page to allow the user to enter Option control information and filter the data being processed. Default filter fields that will appear on the Request Page are defined in the Properties form for the table XMLport Line.
Any desired options that are to be available to the user as part of the Request Page must be defined in the Request Options Page Designer. This Designer is accessed from the XMLport Designer through View | Request Page. The definition of the contents and layout of the Request Options Page is done in essentially the same way as other pages are done. As with any other filter setup screen, the user has complete control of what fields are used for filtering and what filters are applied.