NAV 2009 - Dataports and XMLports

Chapter 10: Dataports and XMLports
CHAPTER 10: DATAPORTS AND XMLPORTS

Objectives
The objectives are:
• Understand the concepts of a dataport and its components.

• Provide an overview of designing dataports.
• Create dataports for export with fixed and a variable format of the
external file.
• Create dataports for import with a fixed and a variable format of the
external file.
• Understand the concepts of XMLport and its components.
• Provide an overview of designing XMLports.
• Create XMLports to be run in the Classic client.
• Create XMLports to be run in the RoleTailored client.
Introduction
Dataports and XMLports are objects that are used for importing data from and
exporting data to external files.
Dataports are used to export data from Microsoft Dynamics® NAV to external
text files, and to import data from external text files into Microsoft Dynamics
NAV. Importing and exporting data is useful when data is collected outside
Microsoft Dynamics NAV and must be incorporated into the database, or when it
must be distributed from the Microsoft Dynamics NAV database to an external
location.
XMLports are used to export and import data to and from external XML
document files. These are similar to dataports, only the XMLport encapsulates
the data in XML format. This lets developers exchange information between
different computer systems in a streamlined way. In Microsoft Dynamics NAV
2009, XMLport is also used to import and export data to and from external text
files, when using the RoleTailored client.
Microsoft Official Training Materials for Microsoft Dynamics ® 10-1

Your use of this content is subject to your current services agreement
C/SIDE Introduction in Microsoft Dynamics® NAV 2009
Dataport Fundamentals
Dataports are used to export and import data to and from external text files.
Dataports can be defined to specifically be used for import or export data, or
both. If the dataport is used for both import and export, only on execution does
the dataport determine whether the process is an import or an export and the
name of the file to read from or to write to.
There are several options for the format of the external file which includes fixed
and variable formats.
The following shows components of a dataport and how they are related.
FIGURE 10.1 DATAPORT COMPONENTS AND THEIR RELATION
The dataport description is the complete description of the dataport and it is

stored in the database. It determines:
• How data is collected.

• How data is formatted when written to the output file.
• What the dataport consists of.
Dataports are created and designed in the Dataport Designer which is accessed
from the Object Designer.
10-2 Microsoft Official Training Materials for Microsoft Dynamics ®

Properties
A property is an attribute of an object, or its component, that characterizes and
specifies behavior of the parent in some ways, such as length and position of a
dataport field in a line during import.
The dataport description contains properties that are related to the dataport itself
and properties that are related to the other components of the dataport, such as
data items, dataport fields or request forms.
Triggers
Certain predefined events that occur to a dataport cause the system to execute a
user-definable C/AL function. The event and the function together are called a
trigger.
Triggers in a dataport can be divided into four categories:
• Dataport triggers
• Data item triggers
• Dataport field triggers
• Request form triggers
Examples of dataport triggers include OnPreDataport that contains statements

that are executed right before the dataport is run, and OnPostDataport that
contains statements that are executed right before the dataport execution is
completed. Triggers in a dataport are edited in the C/AL Editor that can be
opened from the Dataport Designer.
Data Items
The data model of a dataport is built from data items. A data item corresponds to
a table. To retrieve information from tables in the database, define data items.
Data items in a dataport cannot be indented. They have to be processed one at a
time.
Dataport Fields
A dataport field refers to a field in an external file from which data is to be
imported. Dataport fields in the external file are defined either as having a fixed
length, or as delimited by certain characters.
Dataport fields are specified in the Field Designer which can be opened from the
Dataport Designer.

Request Form
The request form is the form that is run before the actual dataport begins
execution. It is used to collect requests and options from the user of the dataport
of things such as the name of the external file.
Design Dataports
Designing a dataport involves several tasks. They are as follows:
• Designing the data model.

• Defining the layout of the external file.
These tasks consist primarily of setting various properties in the dataport objects,
such as dataport properties, data item properties and dataport field properties.
Data Model
The data model is designed by designing data items. A data item corresponds to a
table.
When a dataport is used to export data, each data item in the dataport is iterated
for all records in the underlying table. Sorting order, keys and table views can be
set accordingly. Developers can decide whether the result is written to the
external file or not.
When a dataport is used to import data, records read from the external file are
inserted to the table that corresponds to the data item. Developers can examine
the records before inserting them, specify whether records are inserted
automatically and decide whether records already in the database are overwritten
or updated when a record with the same primary key is read from the external
file. Developers may also determine to omit this record.
External File
The layout of the external file is defined by setting properties which include
setting dataport properties and dataport field properties.
When a dataport is used to export data, these properties describe how the dataport
fields and records must be written to the file.
When a dataport is used to import data, these properties describe how the input
stream must be broken up into records and dataport fields.

Dataport Properties
Dataport properties describe the dataport in general. Several properties, such as
the Import and FileName properties, can be set and reset dynamically. For
example, developers can create a dataport where the user can do one of the
following:
• Select whether to import or export.

• Select the name of the external file to read from or write to.
• Generate a file name automatically when the dataport is run.
The FileFormat property determines the format of the external file. In other
words, it determines the dataport fields' behavior in a record. The following list
shows the options available for the FileFormat property and the dataport fields'
behavior for each option.
FileFormat Remarks
Property
Value
Fixed The dataport fields in a record have a fixed width. Developers
define the starting position and the width of each dataport
field in the record in the Dataport Field Designer.
Variable The dataport fields in a record have varying widths.
Developers define the characters that separate the dataport
fields in the FieldSeparator property.
Data Item Properties

Data Item properties describe the data items of the dataport. Most of these
properties are the same and have the same function as the corresponding
properties of a data item in a report. There are three properties which are special
for data items in a dataport: AutoSave, AutoUpdate, and AutoReplace. They are
used as follows:
Property Remarks
AutoSave This property determines whether imported records are
automatically inserted in a C/SIDE table.
AutoUpdate This property determines whether imported records are
initialized with values from an existing record with the same
primary key.
AutoReplace This property determines whether imported records
automatically replace existing records with the same primary
key.

These three properties determine how records that are read from the external file
are handled. They are also used to resolve the conflict that arises when a record
that is read from the external file during import has the same primary key as a
record that already exists in the database table. The following table shows
combinations of these properties values and their result.
AutoSave AutoUpdate AutoReplace Record Record exists

exists in the only in the
database external file
and in the
external file
No N/A N/A The record in The record from
the database the external file is
is not not automatically
automatically inserted to the
updated or database.
replaced.
Yes No No A runtime The record from
error occurs the external file is
and the automatically
import is inserted to the
stopped. database.
Yes No Yes The record The record from
from the the external file is
external file automatically
replaces the inserted to the
record in the database.
database.
Yes Yes N/A The record The record from
from the the external file is
external file automatically
updates the inserted to the
record in the database.
database.
If the AutoSave property is set to No, the settings of AutoReplace and

AutoUpdate properties have no effect. The insertion or modification is not done
automatically and must be done through C/AL code.
The AutoUpdate property is useful in some particular situations. Its functionality

is best explained by the following example:
• Suppose that a developer has a table that is an item list. The

developer updates the prices by exporting a list that has item
numbers (the primary key) and prices to an external file and then
does some calculations on the prices on a spreadsheet.

• When the prices are calculated and the developer is ready to import
the file that has the new prices, it is obvious that the records read
from the external file have the same primary key as records that are
already in the database.
• Using AutoSave and AutoReplace does not resolve this problem. If
the developer is replacing every record with the corresponding
record from the import file, all the information except the item
numbers and the prices are lost, assuming that the table contains
information other than the item numbers and the prices, such as
name and description of the items.
• AutoUpdate solves this dilemma. When a record is imported, it
actually replaces the existing record, but fields that are not present in
the imported record are initialized with the data from the already
existing record instead of being left empty. The existing record is
updated with the revised information.
Dataport Field Properties

Dataport Field properties describe the dataport fields of a record. If the
FileFormat property is set to Fixed, developers use the StartPos and Width
properties of each dataport field to define how a record that is read from the
external file is to be broken into dataport fields during import. During export,
these properties determine how data from the database is written to the external
file.
During import, when a value is too large for the data type or the defined width of
the database table field where it is to be inserted, an error occurs and stops the
execution. Because the whole dataport is inside a transaction, no traces are left of
this aborted run in the database.
During export, data is converted to text before the export. When the Width
property is smaller than the actual width of the data after conversion, the contents
are truncated from the right until the defined Width. A number is not rounded or
truncated as a number, but as text, from the right.
Developers receive an error at design time if they defined dataport fields that
have starting positions and widths that cause these dataport fields to overlap. This
error prevents compilation of the dataport. However, it is possible to have gaps
between dataport fields. The starting position of the next dataport field does not
have to be exactly where the previous dataport field ended. These gaps may skip
unnecessary information or create blank columns in the file.

If the Field Menu is used to add dataport fields in the Field Designer, the Width
property is set to several default values, depending on the field data type. The
following table shows the default values for the Width property for each field
data type.
Data Type of the Width

Field
Code If actual length > 10, actual length is
used; otherwise, 10.
Text If actual length > 30, actual length is
used; otherwise, 30.
Date 11
Time 10
Option 10
Decimal 12
Integer 7
Boolean 10
Design and Run Dataports

Dataports are created and modified in the Dataport Designer which is accessed
Usually, dataports are run from the Navigation Pane in the Classic client, or from
command buttons in a form, also in the Classic client. The RoleTailored client
does not support dataport objects.
Dataports can also be run from the Object Designer or directly from the Dataport
Designer. If the dataport is run directly from the Dataport Designer and the
dataport is used for import process, no records are actually saved in the database
table.
Demonstration: Create Dataports For Export

There are four fundamental kinds of dataports: importing and exporting, each
with a fixed and a variable format of the external file. The following
demonstration shows how to create dataports for export by using different file
formats.

Create a Dataport to Export to a Fixed Format Text File

The database table that is used in this demonstration is the G/L Account table.
There are several FlowFields among the dataport fields that are exported, and
they have to be calculated when exported. The following steps show how to
create a simple dataport to export fields from the G/L Account table, by using a
fixed format external file.
1. In the Object Designer's Dataport List, click the New button. The
Dataport Designer opens.
2. Open the Properties window for the dataport and set the following
properties:
o Import: No (This specifies the dataport to be used only for
export.)
o FileFormat: Fixed (This specifies the external file to have fixed
format.)
3. Close the Properties window.

4. Click the first empty line in the Dataport Designer, and type or select
the number or name of table 15, G/L Account in the DataItem
column. By the default, the Name column is set to the table name.
5. While the G/L Account data item is still selected, click View,
Dataport Fields. The Field Designer opens.
6. Type the following in the Field Designer:
SourceExpr StartPos Width

"No." 1 20
Name 22 30
"Balance at Date" 53 12
"Net Change" 66 12
NOTE: Instead of typing the fields manually, use the Field Menu to add multiple
fields from the table to the Field Designer.
7. Close the Field Designer and open the Properties window for the G/L
Account data item, and set the following property:
o CalcFields: Balance at Date,Net Change
NOTE: Instead of typing the value directly to the CalcFields property, click the
Assist-Edit button on the CalcFields property to open the Field List window. Add
the fields in the Field List window and then click OK.

9. Compile and save the dataport by clicking File, Save As. The Save
As dialog box opens.
10. Type 90000 in the ID field and G/L Account Export Fixed in the
Name field, ensure that the Compiled check box is selected, and
then click OK. This compiles and saves the dataport.
11. Close the dataport.
Run the Dataport

The following steps show how to run the dataport from the Object Designer.
1. In the Object Designer's Dataport list, select dataport 90000, G/L

Account Export Fixed, and then click the Run button. The request
form opens.
2. Click the Options tab, and then click the Assist-Edit button on the
File Name text box. The Dataport Export File Name dialog opens.
3. Select Desktop in the Save In drop-down list, type GLAccountFixed
in the File Name text box, and then click Save.
4. Click OK on the request form. The dataport runs and creates the
GLAccountFixed.txt file in the Desktop.
5. Open the GLAccountFixed.txt in a Notepad.
FIGURE 10.2 THE GLACCOUNTFIXED.TXT IN NOTEPAD
Refine the Dataport

Several things can be done to refine the newly created dataport to make it more
user-friendly. This includes the following:
• Removing the first tab in the request form so that users cannot set
filters and keys.
• Setting the dataport to export only accounts where the Account Type
is Posting or End-Total.
• Formatting the numbers as thousands. There must be no thousand
separators, no decimals, and the sign must be prefixed.

Change the Request Form

The UseReqForm property specifies whether the dataport displays the request
form before its execution. If no file name is set, setting this property to No
(disabling the request form) causes a run-time error.
To remove the tabs that correspond to the data items in the request form, clear the
ReqFilterFields property and set a sorting key in the DataItemTableView
property of the data items.
The following steps show how to remove the G/L Account tab from the request
form.
1. Design dataport 90000, G/L Account Export Fixed from the Object
Designer.
2. Open the Properties window for the G/L Account data item and set
the DataItemTableView property to SORTING(No.)
3. Close the Properties window and then compile, save and close the
dataport.
4. Run the dataport. Notice the request form only shows one tab, the
Options tab.
FIGURE 10.3 THE REQUEST FORM
Select Specific Filters

The following steps show how to select only some account types, by creating a
table filter through setting DataItemTableView property.
Designer.
2. Open the Properties window for the G/L Account data item.
3. Click the Assist-Edit button on the DataItemTableView property to
open the Table View window.

4. Click the Assist-Edit button on the Table Filter field to open the
Table Filter window, and type the following:
Field Type Value

Account Type Filter Posting|End-
Total
This creates a table filter that selects records where Account Type is Posting or
End-Total (the character between the two values is a | (pipe) which means OR).
5. Click OK to close the Table Filter window, and then click OK to

close the Table View window. The DataItemTableView is set to
SORTING(No.) WHERE(Account Type=FILTER(Posting|End-
Total)).
6. Close the Properties window, and then compile, save and close the
dataport.
7. Run the dataport, save the external file as GLAccountFixed2.txt and
view the text file.
Change the Formatting of Numbers

The following steps show how to export the decimal fields, Balance at Date and
Net Change as thousands so that the number 1,444,723.67 is exported as 1444,
by setting the SourceExpr property of these fields.
Designer.
2. With the G/L Account data item selected, click View, Dataport
Fields. The Field Designer opens.
3. Open the Properties window for the Balance at Date field, and set
the following property:
o SourceExpr: FORMAT(ROUND("Balance at
Date"/1000,1,'='),0,1)
In this expression, the Balance at Date field is first divided by 1000. The result
is rounded by the ROUND function, and then the FORMAT function is used to
display the return value from the ROUND function in format 1 (which for a
decimal value means <Sign><Integer><Decimals>).
4. Open the Properties window for the Net Change field, and set the
following property:
o SourceExpr: ROUND("Net Change"/1000,1,'=')
o Format: <Sign><Integer><Decimals>
NOTE: This achieves the same effect as setting the SourceExpr property with
FORMAT function, as in the Balance at Date field.

5. Close the Properties window, and then compile, save and close the
dataport.
6. Run the dataport, save the external file as GLAccountFixed3.txt and
view the text file.
FIGURE 10.4 THE GLACCOUNTFIXED3.TXT IN NOTEPAD
Create a Dataport to Export to a Variable Format Text File

Now create a dataport that exports the same records as in the previous example,
but in a variable format. Each dataport field in a record is delimited by characters
that are defined in the FieldSeparator property and has the width of only the
actual data of the dataport field, in each record. The following steps show how to
create a dataport to export fields from the G/L Account table, by using a variable
format external file.
Designer.
2. Compile and save the dataport with the ID 90001, and the name G/L
Account Export Variable.
3. Open the Properties window for the dataport, set the following
properties:
o FileFormat: Variable
o FieldStartDelimiter: <None>
o FieldEndDelimiter: <None>
o FieldSeparator: ;
The semicolon is used as the field separator because the dataport fields include
both space characters and commas. Another solution is to use the delimiters. In
that case, the field separator can be a comma. Set these properties appropriately,
depending on the target application for the exported file or which formats that the
application supports when it is importing text files. Leave the RecordSeparator
and the DataItemSeparator properties as they are. This means the records are
separated by new lines and data items are separated by two new lines. Setting the
FileFormat property to Variable tells C/SIDE to ignore values set in the StartPos
and Width properties of the dataport fields.

4. Close the Properties window, and compile, save and close the
dataport.
5. Run the dataport, save the external file as GLAccountVariable.txt
and view the text file.
FIGURE 10.5 THE GLACCOUNTVARIABLE.TXT IN NOTEPAD
Demonstration: Create Dataports For Import

The following demonstration shows how to create dataports for import by using
different file formats.
Create a Fixed Format Text File

Creating a dataport for import is no different from creating a dataport for export.
However, consider how the imported records must be inserted in the database
table. This is especially relevant if the table already contains records with the
same primary key as some records to be imported.
The database table that is used in this demonstration is the Vehicle table (created
earlier in the course - Chapter 2: Tables.) Before creating the dataport for import,
create the text file to be used as the import file. The following steps show how to
create a fixed format text file that contains records to be imported to the Vehicle
table.
1. Open the Notepad.

2. Type the following:
FIAT 1000 Black 5-Speed 01/31/10

MAZDA 7500 Blue Automatic 01/15/10
FIAT 2000 Ivory Automatic 03/31/10
MAZDA 5500 Red 5-Speed 02/10/10
3. Save the file as VehicleFixed.txt and close the Notepad.

Create a Dataport to Import from a Fixed Format Text File

The following steps show how to create a dataport to import fields from an
external file to the Vehicle table, by using a fixed format external file.
1. In the Object Designer's Dataport List, click the New button. The
Dataport Designer opens.
2. Open the Properties window for the dataport and set the following
properties:
o Import: Yes (This specifies the dataport to be used only for
import.)
o FileFormat: Fixed (This specifies the external file to have fixed
format.)

4. Click the first empty line in the Dataport Designer, and type or select
the number or name of table 90000, Vehicle in the DataItem column.
By the default, the Name column is set to the table name.
Decide how the lines in the import file are broken down into dataport fields; each
line becomes a record in the data item. The lines have a fixed format, and by
carefully looking at the layout of the lines, deduce the field starting positions.
5. While the Vehicle data item is still selected, click View, Dataport
Fields. The Field Designer opens.
6. Type the following in the Field Designer:
SourceExpr StartPos Width

Model 1 7
"Serial No." 8 6
Description 14 8
Transmission 22 11
"List Price" 33 7
"Date of 40 11
Manufacturing"
7. Close the Field Designer.

8. Compile and save the dataport with the ID 90002, and the name
Vehicle Import Fixed, and close the dataport.
9. Run table 90000, Vehicle, from the Object Designer.
10. Delete all the records in the table, and close the table.
11. Run the dataport. The request form opens.

12. In the request form Options tab, select VehicleFixed.txt created

earlier as the file to import, and then click OK.
13. Run table 90000, Vehicle and view the changes. The table now
contains the imported record.
FIGURE 10.6 THE VEHICLE TABLE
Because Model and Serial No. are the fields in the primary key of the table, the
records are displayed in an order determined by these fields, not the in the order
shown in the import file.
Possible Errors
Always test imports carefully before using them for production. It is easy to
make errors when deciding how to divide up the lines in the import file. In some
cases, the rearrangement of records generates a run-time error when the dataport
is run. Consider, for example, if an error is made in setting up a dataport field (of
type Integer in the table) so that it is assigned a width that is one character too
wide. For most of the import file, this makes no difference at all - the resulting
trailing space is ignored. But the line that begins with "112Oven..." can provoke a
run-time error if C/SIDE reads 112O instead of 112. The "O" (uppercase "O")
cannot be inserted into an integer field. In cases such as these, it is fortunate to
provoke a run-time error. In other cases, the error may not be detected by
C/SIDE, for example, if the cut between two text fields is positioned incorrectly.
Create a Variable Format Text File

The following steps show how to create a variable format text file that contains
records to be imported to the Vehicle table.

FIAT,1000,Black,5-Speed,15000,01/31/10
FIAT,2000,Ivory,Automatic,40000,03/31/10
MAZDA,5500,Red,5-Speed,30000,02/10/10
MAZDA,7500,Blue,Automatic,25000,01/15/10

3. Save the file as VehicleFixed.txt and close the Notepad.
Create a Dataport to Import from Variable Format Text File

The following steps show how to create a dataport to import fields from an
external file to the Vehicle table, by using variable format external file.
1. Design dataport 90002, Vehicle Import Fixed, from the Object

Designer.
2. Compile and save the dataport with the ID 90003, and the name
Vehicle Import Variable.
3. Open the Properties window for the dataport, and set the following
properties:
o FileFormat: Variable
o FieldSeparator: ,
o FieldStartDelimiter: <None>
o FieldEndDelimiter: <None>
These are the only differences between the fixed format dataport and variable
format dataport.
dataport.
7. Run the dataport. The request form opens.
8. In the request form Options tab, select VehicleVariable.txt as the file
to import, and then click OK.
9. Run table 90000, Vehicle and view the changes. The table now
contains the imported record.
The result of running this dataport is the same as running the dataport with a
fixed format.
XMLPort Fundamentals
XMLports are used to export and import data to and from external XML
document files. XML documents created by XMLports encapsulate the data in
XML format. This enables exchanging information between different computer
systems in a streamlined manner.
In Microsoft Dynamics NAV 2009, XMLports replace dataports as means of

exporting and importing data in the RoleTailored client. This means, XMLports
are not only limited to only XML document files, but also support text files,
when they are run in the RoleTailored client.

The following shows components of an XMLport and how they are related.
FIGURE 10.7 XMLPORT COMPONENTS AND THEIR RELATION
The XMLport description is the complete description of the XMLport and it is

stored in the database. It determines:
• How data is collected.

• How data is formatted when written to the output file.
• What the XMLport consists of.
XMLports are created and designed in the XMLport Designer which is accessed
Properties
A property is an attribute of an object, or its component, that characterizes and
specifies behavior of the parent in some ways, such as the type of a node in
XMLport.
The XMLport description contains properties that are related to the XMLport
itself and properties that are related to the other components of the XMLport,
such as nodes and request pages.
Triggers
Certain predefined events that occur to an XMLport cause the system to execute
a user-definable C/AL function. The event and the function together are called a
trigger.
Triggers in an XMLport can be divided into three categories:
• XMLport triggers
• Node triggers
• Request page triggers

Nodes
Instead of fields, XMLports have nodes. Nodes form the structure of XMLport
and the structure of the XML document or text file which is to be imported from
or exported to. Each node has several important properties, some can be accessed
directly from the XMLport Designer. They are as follows:
Node Remarks
Property
Node Name Used to specify the XML node name of the XML element or
attribute. Node names must be entered in the order in which
they appear in the XML document. Parent elements must
precede their child elements. Indent the node names of child
elements under their parent elements by using one
indentation per level. List attributes under the elements that
they define and indent them to the child level.
Node Type Used to specify whether the name in the Node Name
represents data of type element or attribute. The drop-down
list in the NodeType field contains two options: Element and
Attribute. The default setting is Element.
Source Type Used to specify the data structure that the Node Name
corresponds to. The SourceType field contains a drop-down
list that contains three options: Text, Table, and Field. The
default setting is Text.
Data Source Used together with the Source Type to specify the data
source from the data structure.

The following list explains more about Source Type options:
Source Type Remarks

Value
Text Select this option when the XML data cannot be mapped
directly to the database or when the database does not need
the information. The value of the Text field is put into a text
variable specified in the VariableName property. Otherwise
the node name is used by default. The text variable functions
like a global C/AL text variable. The text source type can be
changed into a big text variable by setting the TextType
property to BigText.
Table Select this option to indicate that a node is equal to a table or
that a table record must be initialized. As with the Text
option, specify a variable name for the table which also
functions like a global record variable. By default, the
variable name is the name of the table.
Field Select this option to indicate that a node is equal to a field in
the database. However, for this selection to be valid, a table
must be declared as the parent of the field. Failure to do this
causes an error when compiling the XMLport object.
The Data Source has the following interactions with the Source Type:
• If Table is specified as the Source Type, clicking the Assist-Edit

button on the DataSource field opens the Table List window. Select
a table from the Table List window or by setting the SourceTable
property of the node.
o If a variable name is defined for the table, the format of the value
that is shown in the DataSource field will be
TableVariableName(tablename).
o If a variable name is not defined, the format of the value is
displayed as <tablename>(tablename).
• If Field is specified as the Source Type, clicking the Assist-Edit

button on the DataSource field opens the Field Lookup window.
Select a field from the Field Lookup window or by setting the
Sourcefield property of the node. The format of the value is
displayed as tablevariablename::fieldname.

Request Page
The request page is the page that is run before the actual XMLport begins
execution. It is used to collect requests and options from the user of the XMLport
of things such as filtering.
Generally, request pages in XMLports and request pages in reports are similar.
They have similar filter functionality grouped in FastTabs and developers can
add more controls by creating other FastTabs.
Request page in XMLport only has OK and Cancel buttons (compared to Print,
Preview and Cancel buttons in request page in reports) regardless whether the
XMLport is used for importing or exporting text or XML documents. Request
page is displayed only when XMLports are run in the RoleTailored client.
Design XMLports
An XML document contains XML nodes which determine the nature of the
content that they contain.
To create an XMLport to import data from an XML document, specify all the
XML nodes (specify node names) and indicate the type of each, whether it
represents an element or an attribute. Map these nodes to corresponding data
structures (tables, records or fields) in the Microsoft Dynamics NAV database.
When an XMLport object is called to handle an incoming XML document, it
reads the incoming data stream and performs the processing and database actions.
To create an XMLport to export data to an XML document, build the node

structure of the XML document by using the XMLport Designer and map the
data. When an XMLport object is called to export data, it reads the required data
from the database, adds the necessary XML nodes to form the XML document,
and writes the document to a data stream.
XMLports do not handle XML documents that do the following:
• Modify existing data in the database.

• Find and delete data in the database.
• Query the database for data, such as item catalog information.
For incoming documents of these types, use C/AL code to perform the necessary
database manipulation to achieve the desired result.
Designing an XMLport is actually designing the structure of the external file,

whether it is an XML document or a text file. This consists primarily of setting
various properties in the XMLport objects, such as XMLport properties and Node
properties.

XMLport Properties
The XMLport properties describe the XMLport in general. Several properties,
such as the Direction and FileName properties, can be set and reset dynamically.
For example, developers can create an XMLport where the user can do one of the
following:
• Select whether to import or export.

• Select the name of the external file to read from or write to.
• Generate a file name automatically when the XMLport is run.
The Format property determines the format of the external file. In other words, it
determines the XMLport nodes behavior in a record. The following list shows the
options available for the Format property.
Format Remarks
Property
Value
XML The XMLport handles XML documents.
Fixed Text The XMLport handles text file that has fixed format.
Variable Text The XMLport handles text file that has variable format.
Node Properties
The node properties describe the node of the XMLport which defines the
structure of the XMLport. The following list shows examples of node properties.
Property Name Remarks

Indentation Sets the indentation level of an element or attribute
in the XMLport Designer.
NodeName Specifies the name of a node in an XML document.
This property can also be accessed directly in the
XMLport Designer.
NodeType Specifies whether an XML object is an element or
an attribute.
SourceType Specifies what a particular node in the XMLport
designer corresponds to in the Microsoft Dynamics
NAV database. This property can also be accessed
directly in the XMLport Designer.
SourceTable Selects the table to be mapped to XML data (import)
or the table from which data is to be exported. This
property can also be accessed from the Data Source
field in the XMLport Designer.

Property Name Remarks

SourceField Selects the field that is to be mapped to XML data.
This propery can also be accessed from the Data
Source field in the XMLport Designer.
TextType Specifies which type of text this element or attribute
contains.
FieldValidate Specifies whether the values in the source field must
be validated by the OnValidate trigger for the field.
VariableName Specifies a variable name for the table specified in
the SourceTable property. Also used to specify a
variable name for the text if it is specified in the
SourceType property.
SourceTableView Used to filter the data in the table set as the source
for this XML item.
CalcFields Calculates automatically the information for
FlowFields entered here.
AutoCalcField Determines whether the value in the FlowField must
be recalculated before the field is exported.
LinkTable Determines to which table the XML item must be
linked, and can only be used for the SourceType of
Table.
LinkTableForceInsert Specifies whether data from the linked table must be
forcibly inserted into a table to prevent the system
from generating an error.
LinkFields Specifies the fields from the two tables that are
linked by the LinkTable property. This is available
only for XML items with Table as the data source.
Temporary Creates a temporary table in the XMLport.
MinOccurs Specifies the minimum number of times that an
element can occur.
MaxOccurs Specifies the maximum number of times that an
element can occur.
Occurrence Specifies whether an attribute must occur in the data
being imported or exported.

Properties for Handling Text Files

There are several properties of XMLport and XMLport node which are specific
for XMLports that handle text files, when they are run in the RoleTailored client.
These properties are as follows:
Name Type Property Description

Of
Format Option XMLport Determines the import/export
format of the XMLport.
The options are as follows:
• XML
• Variable Text
• Fixed Text
Width Integer Nodes Determines the width of the
(elements fixed width field.
and/or If Fixed Length is selected in
attributes) the Format property, all
elements and attributes of type
Text and Field should have
their Width property value set
to greater than 0, or it gives
compilation errors.
FieldDelimiter String XMLport Determines what the text
delimiter is for a field.
The default value is a quotation
mark (").
FieldSeparator String XMLport Determines what the field
separator is for fields.
The default value is a comma
(,).
RecordSeparator String XMLport Determines what the record
separator is for records.
The default value is
<NewLine>.
TableSeparator String XMLport Determines what the table
separator is for tables.
The default value is
<NewLine><NewLine>.

Design and Run XMLports

XMLports are created and modified in the XMLport Designer which is accessed
from the Object Designer. However, XMLports are always run from another
object. They cannot be run directly from the Object Designer.
To test run an XMLport before integrating it to the rest of the application, create
a test codeunit that calls the XMLport and streams data to or from a file,
depending on whether it is an import or an export process. The following shows a
test codeunit to run an XMLport.
FIGURE 10.8 THE TEST CODEUNIT
The four functions in the OnRun trigger perform the following:
• Open the Import.xml file.

• Create an InStream object so that the XML data can be streamed
from the file.
• Load a specific XMLport object and give it the source from which it
shall read and parse the incoming XML data stream.
• Close the Import.xml file.
In Microsoft Dynamics NAV 2009, XMLports can be run from:
• Menu suites designed for the RoleTailored Client.

• RunObject property of controls in page objects.
• Codeunits.
An XMLport instance can be created as a variable of type XMLport and the

instance has a RUN method, similar to the dataport RUN method.

Demonstration: Create XMLports For Use In The Classic

Client
The following demonstration shows how to create XMLports for the Classic
client.
Create an XMLport to Export to XML Documents

The following steps show how to create an XMLport to export data from the G/L
Account table to an external XML document.
1. In the Object Designer's XMLport List, click the New button. The
XMLport Designer opens.
2. Open the Properties window for the XMLport and set the following
properties:
o Direction: Export (This specifies the XMLport to be used only
for export.)
o Format: Xml (This specifies the external file to be an XML
document.)

4. Click the first empty line in the XMLport Designer, and type the
following:
Node Name Node Type Source Type

Root Element Text
5. Go to the next line and type the following to add a source table.
Ensure that it is indented under the Root element.
Node Name Node Type Source Type Data Source

GLAccount Element Table 15
NOTE: The G/L Account table ID is 15. Instead of typing 15 directly to the Data
Source field, use the LookUp button on the Data Source field and select the G/L
Account table.

6. Go to the next line and type the following on the next few lines to
add several fields from the G/L Account table. Ensure that they are
indented under the GL Account element.
Node Name Node Source Data Source

Type Type
No Element Field G/L Account::No.
Name Element Field G/L Account::Name
BalanceAtDate Element Field G/L Account::Balance at
Date
NetChange Element Field G/L Account::Net Change
NOTE: Instead of typing the value to the Data Source field, use the LookUp
button to open the Field Lookup window and select the fields from the Field
Lookup window.
7. Open the Properties window for the G/L Account element, and set
the following property:
o SourceTableView: SORTING(No.) WHERE(Account
Type=FILTER(Posting|End-Total))
o CalcFields: Balance at Date,Net Change
NOTE: Instead of typing the value directly to the CalcFields property, click the
Assist-Edit button on the CalcFields property to open the Field List window. Add
the fields in the Field List window and then click OK. Also, instead of typing the
value to the SourceTableView property, use the Assist-Edit button to open the
Table View window and assign the property value.

9. Compile and save the XMLport by clicking File, Save As. The Save
10. Type 90000 in the ID field and G/L Account Export XML in the
then click OK. This compiles and saves the XMLport.
FIGURE 10.9 THE G/L ACCOUNT EXPORT XML XMLPORT

11. Close the XMLport.
Create a Codeunit to Run the XMLport

The following steps show how to create a codeunit to run the XMLport.
1. In the Object Designer's Codeunit List, click the New button. The
C/AL Editor opens.
2. Click View, C/AL Globals.
3. In the Variables tab, type the following:
Name DataType
TestFile File
TestStream OutStream
4. Close the C/AL Globals window.

5. Click the first line under the OnRun trigger, and type the following:
TestFile.CREATE('C:\GL Account Export.xml');

TestFile.CREATEOUTSTREAM(TestStream);
XMLPORT.EXPORT(XMLPORT::"G/L Account Export
XML",TestStream);
TestFile.CLOSE;
MESSAGE('G/L Account Export Xml completed!');
This codeunit creates a new text file "C:\GL Account Export.xml."

6. Compile and save the codeunit by clicking File, Save As. TheSave
7. Type 90004 in the ID field and XML Export - G/L Account in the
then click OK. This compiles and saves the codeunit.
8. Run the codeunit and view the result.
9. Locate the new file "C:\GL Account Export.xml" on the system.
Double-clicking this file opens it in the browser. The following
figure shows the XML file:
FIGURE 10.10 THE GL ACCOUNT EXPORT.XML

Create an XML Input File

The database table that is used in the following demonstration is the Vehicle
table (created earlier in the course - Chapter 2: Tables.) Before creating the
XMLport for import, create the XML file to be used as the import file. The
following steps show how to create an XML file containing records to be
imported to the Vehicle table.

<Root>
<Vehicle>
<Model>FIAT</Model>
<SerialNo>1000</SerialNo>
<ListPrice>15,000</ListPrice>
</Vehicle>
<Vehicle>
<Model>FIAT</Model>
</Vehicle>
<Vehicle>
<Model>MAZDA</Model>
</Vehicle>
<Vehicle>
<Model>MAZDA</Model>
</Vehicle>
</Root>
3. Save the file as VehicleXML.xml and close the Notepad.
Create an XMLport to Import from XML Documents

The following steps show how to create an XMLport to import data from an
external XML document to the Vehicle table.
1. In the Object Designer's XMLport list, click the New button. The
properties:
o Direction: Import (This specifies the XMLport to be used only
for import.)
o Format: Xml (This specifies the external file to be an XML
document.)


following:

Root Element Text

Vehicle Element Table 90000
add several fields from the Vehicle table. Ensure that they are
indented under the Vehicle element.
Node Name Node Type Source Data Source

Type
Model Element Field Vehicle::Model
SerialNo Element Field Vehicle::Name
ListPrice Element Field Vehicle::List
Price
8. Type 90001 in the ID field and Vehicle Import XML in the Name
field, ensure that the Compiled check box is selected, and then click
OK. This compiles and saves the XMLport.
Create a Codeunit to Run the XMLport

The following steps show how to create a codeunit to run the XMLport.
1. In the Object Designer's Codeunit list, click the New button. The
C/AL Editor opens.

2. Click View, C/AL Globals.

3. In the Variables tab, type the following:
Name DataType
TestFile File
TestStream InStream
4. Close the C/AL Globals window.

5. Click the first line under the OnRun trigger, and type the following:
TestFile.OPEN('C:\VehicleXML.xml');
TestFile.CREATEINSTREAM(TestStream);
XMLPORT.IMPORT(XMLPORT::"Vehicle Import XML",TestStream);
TestFile.CLOSE;
MESSAGE('Vehicle Import Xml completed!');
This codeunit imports an XML file "C:\VehicleXML.xml."
6. Compile and save the codeunit by clicking File, Save As. TheSave
7. Type 90005 in the ID field and XML Import - Vehicle in the Name
OK. This compiles and saves the codeunit.

10. Run the codeunit and then run table 90000, Vehicle, from the Object
Designer and view the result. The table now contains the imported
record.
FIGURE 10.11 THE VEHICLE TABLE
Demonstration: Create XMLports For Use In The RoleTailored

Client
The following demonstration shows how to create XMLports for the
RoleTailored client.
Transfer a File From NAV Server to the Client

The codeunit 90004, XML Export - G/L Account which is created in the earlier
demonstration, exports data from the G/L Account table to an XML document.
In the new three-tier architecture, the business logic is run on the middle-tier
server and not on the client. This means that in Microsoft Dynamics NAV, files
are created on the Microsoft Dynamics NAV service and not locally on the client
computer as is the case in the Classic client. There are several built-in functions
which are used to transfer files from and to Microsoft Dynamics NAV service to
the RoleTailored client, such as the DOWNLOAD and the UPLOAD functions.
In addition, the ISSERVICETIER function is used to determine whether code is
run in the Classic client or Microsoft Dynamics NAV service.

The following steps show how to run the codeunit 90004, XML Export - G/L
Account, from a page in the RoleTailored client.
1. Design codeunit 90004, XML Export - G/L Account from the

Object Designer.
2. Add the following global variables:
Name DataType
ToFile Variant
3. Modify the code in the OnRun trigger as follows:
TestFile.CREATE('C:\GL Account Export.xml');

TestFile.CREATEOUTSTREAM(TestStream);
XMLPORT.EXPORT(XMLPORT::"G/L Account Export
XML",TestStream);
TestFile.CLOSE;
ToFile := 'thefile.xml';
IF ISSERVICETIER THEN
DOWNLOAD('C:\GL Account Export.xml','Downloading
file..','C:\','',Tofile);
MESSAGE('G/L Account Export Xml completed!');
4. Compile, save and close the codeunit.
Run the Codeunit From a Page

The following steps show how to run the codeunit from page 90001, Custom
Page.
1. Design page 90001, Custom Page, from the Object Designer.

2. Open the Action Designer for the page.
3. Type the following on the empty line:
Caption Type
Run Codeunit Action
4. Set the RunObject property of the action to Codeunit XML Export -

G/L Account.
5. Compile, save and close the page. Run the page and run the action.

Run an XMLport Directly From a Page

An XMLport can be run directly from an action in a page. The following steps
show how to run an XMLport directly from a page in the RoleTailored client.

Caption Type
Run XMLport Action
4. Set the RunObject property of the action to XMLport G/L Account

Export XML.
Create an XMLport to Export to Variable Format Text File
1. Design XMLport 90000, G/L Account Export Xml, from the

Object Designer.
2. Compile and save the XMLport with the ID 90002, and the name
G/L Account Export Variable.
3. Open the Properties window for the XMLport, and set the following
properties:
o Format: Variable Text
o FieldSeparator: ,
o FieldDelimiter: <None>
XMLport.
6. Open the Action Designer for the page and type the following on the
empty line:
Caption Type
Run XMLport Action
Variable Text
7. Set the RunObject property of the action to XMLport G/L Account

Export Variable.

Lab 10.1 - Create XMLports

The following lab tests the basic knowledge on how to create XMLports.
Scenario
Simon is a developer working for CRONUS International Ltd. CRONUS

International has decided to start selling Microsoft Dynamics NAV training
courses as its business.
Simon has already created a Course table to record course information and Card
and List pages to interface the Course table. Now, Simon must create XMLports
to export all the course details from the Course List page, in the following
format:
• Comma-separated text file.

• XML file.
Challenge Yourself!
1. Create an XMLport for export to variable format text file.

2. Create an XMLport for export to XML document.
3. Add actions in the Course List page to run the XMLports.
Need a Little Help?

Create an XMLport for export to variable format text file.
1. Create a new XMLport.

2. Set the XMLport properties for variable format.
3. Define the XMLport nodes.
Create an XMLport for export to XML document.
1. Design and save the previous XMLport to a new XMLport.

2. Set the XMLport properties for XML document.
Add actions in the Course List page to run the XMLports.
1. Design page 90011, Course List, from the Object Designer.

2. Add ActionContainer and two actions.
3. Set the two actions property to run the respective XMLport.

Step by Step
Create an XMLport for export to variable format text file.
1. In the Object Designer's XMLport List, click the New button. The
properties:
o Direction: Export (This specifies the XMLport to be used only
for export.)
o Format: Variable Text (This specifies the external file to be an
XML document.)
o FieldSeparator: ,
o FieldDelimiter: <None>

following:

Root Element Text

Course Element Table 90010
add several fields from the G/L Account table. Ensure that they are
indented under the GL Account element.

Type Type
Code Element Field Course::Code
Name Element Field Course::Name
Description Element Field Course::Description
Type Element Field Course::Type
Duration Element Field Course::Duration


Type Type
Price Element Field Course::Price
Active Element Field Course::Active
Difficulty Element Field Course::Difficulty
PassingRate Element Field Course::Passing Rate
8. Type 90010 in the ID field and Course Export Variable in the Name
OK. This compiles and saves the XMLport.
Create an XMLport for export to XML document.
1. Design XMLport 90010, Course Export Variable, from the Object

Designer.
2. Compile and save the XMLport with the ID 90011, and the name
Course Export XML.
3. Open the Properties window for the XMLport, and set the following
properties:
o Format: Xml
XMLport.
Add actions in the Course List page to run the XMLports.
1. Design page 90011, Course List, from the Object Designer.

Type SubType
ActionContainer ActionItems

4. Type the following on the next lines and indent them under the
ActionContainer.
Caption Type
Run XMLport Action
Variable
Run XMLport Action
XML
5. Open the Properties window for the RunXMLport Variable action

and set the RubObject property to XMLport Course Export Variable.
6. Open the Properties window for the RunXMLport XML action and
set the RubObject property to XMLport Course Export XML.
8. Compile, save and close the page.

Summary
Dataports and XMLports are objects that are used for importing data from and
exporting data to external files.
Use dataports to export data from Microsoft Dynamics NAV or import data into
Microsoft Dynamics NAV instead of XMLports in the following scenarios:
• To support businesses that use earlier versions of Microsoft

Dynamics NAV.
• To modify Microsoft Dynamics NAV data in a tool that does not
support XML.
The Microsoft Dynamics NAV RoleTailored client uses XMLports as ways to

export and import data from and to Microsoft Dynamics NAV database.
Therefore, in the RoleTailored client, XMLport functionalities are extended to
handle text files, both in the fixed and variable format. Special precautions are
needed when transferring files from Microsoft Dynamics NAV service to the
client.

Test Your Knowledge

1. What is the difference between the description of a report and the description
of a dataport?
2. What cannot be done with a data item in a dataport that can be done with a
data item in a report?
3. In an import dataport, what must the dataport fields created in the Dataport
Field Designer match?
4. In an import dataport, if the AutoSave property is set to No and the

AutoUpdate property is set to Yes, what does the dataport do with the
records from the external file?
5. When must the StartPos and Width properties of a dataport field be used?
6. True or False. Every dataport field must be bound to a real field in the data
item.
7. What does the Calcfields property do on a data item?
8. When exporting, which dataport file type lines up the information in

columns?
9. When exporting, which dataport file type creates the smallest possible file?
10. When importing, which dataport properties can be set so that the user cannot
view the options tab?
11. What is the main difference between a Dataport and an XMLport?
12. The XML node name information is stored in what field?
13. Which field is used to specify whether the name in the NodeName field
represents data of the type element or attribute?
14. Which field specifies the data structure that the node name corresponds to in
the Microsoft Dynamics NAV database?
15. How are the XMLports run?
16. True or False. An XMLport cannot modify existing data in the database.
17. What is the purpose of the Direction property in the XMLport?

Quick Interaction: Lessons Learned

Take a moment and write down three key points you have learned from this
chapter
1.
2.
3.


NAV 2009 - Dataports and XMLports

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

NAV 2009 - Dataports and XMLports

Uploaded by

Copyright:

Available Formats

Chapter 10: Dataports and XMLports

CHAPTER 10: DATAPORTS AND XMLPORTS

• Understand the concepts of a dataport and its components.

Microsoft Official Training Materials for Microsoft Dynamics ® 10-1

FIGURE 10.1 DATAPORT COMPONENTS AND THEIR RELATION

The dataport description is the complete description of the dataport and it is

• How data is collected.

10-2 Microsoft Official Training Materials for Microsoft Dynamics ®

Triggers in a dataport can be divided into four categories:

Examples of dataport triggers include OnPreDataport that contains statements

Microsoft Official Training Materials for Microsoft Dynamics ® 10-3

• Designing the data model.

10-4 Microsoft Official Training Materials for Microsoft Dynamics ®

• Select whether to import or export.

Data Item Properties

Microsoft Official Training Materials for Microsoft Dynamics ® 10-5

AutoSave AutoUpdate AutoReplace Record Record exists

If the AutoSave property is set to No, the settings of AutoReplace and

The AutoUpdate property is useful in some particular situations. Its functionality

• Suppose that a developer has a table that is an item list. The

10-6 Microsoft Official Training Materials for Microsoft Dynamics ®

Dataport Field Properties

Microsoft Official Training Materials for Microsoft Dynamics ® 10-7

Data Type of the Width

Design and Run Dataports

Demonstration: Create Dataports For Export

10-8 Microsoft Official Training Materials for Microsoft Dynamics ®

Create a Dataport to Export to a Fixed Format Text File

3. Close the Properties window.

SourceExpr StartPos Width

8. Close the Properties window.

Microsoft Official Training Materials for Microsoft Dynamics ® 10-9

Run the Dataport

1. In the Object Designer's Dataport list, select dataport 90000, G/L

FIGURE 10.2 THE GLACCOUNTFIXED.TXT IN NOTEPAD

Refine the Dataport

10-10 Microsoft Official Training Materials for Microsoft Dynamics ®

Change the Request Form

FIGURE 10.3 THE REQUEST FORM

Select Specific Filters

Microsoft Official Training Materials for Microsoft Dynamics ® 10-11

Field Type Value

5. Click OK to close the Table Filter window, and then click OK to

Change the Formatting of Numbers

10-12 Microsoft Official Training Materials for Microsoft Dynamics ®

FIGURE 10.4 THE GLACCOUNTFIXED3.TXT IN NOTEPAD

Create a Dataport to Export to a Variable Format Text File

Microsoft Official Training Materials for Microsoft Dynamics ® 10-13

FIGURE 10.5 THE GLACCOUNTVARIABLE.TXT IN NOTEPAD

Demonstration: Create Dataports For Import

Create a Fixed Format Text File

1. Open the Notepad.

FIAT 1000 Black 5-Speed 01/31/10

3. Save the file as VehicleFixed.txt and close the Notepad.

10-14 Microsoft Official Training Materials for Microsoft Dynamics ®

Create a Dataport to Import from a Fixed Format Text File

3. Close the Properties window.

SourceExpr StartPos Width

7. Close the Field Designer.

Microsoft Official Training Materials for Microsoft Dynamics ® 10-15

12. In the request form Options tab, select VehicleFixed.txt created

FIGURE 10.6 THE VEHICLE TABLE

Create a Variable Format Text File