Na2009 enus devi_10

Chapter 10: Dataports and XMLports

10-1

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 ® Your use of this content is subject to your current services agreement

C/SIDE Introduction in Microsoft Dynamics® NAV 2009

10-2

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-3

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.



10-4

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.



10-5

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 Property Value

Remarks

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.



10-6

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 exists in the database and in the external file

Record exists only in the external file

No N/A N/A The record in the database is not automatically updated or replaced.

The record from the external file is not automatically inserted to the database.

Yes No No A runtime error occurs and the import is stopped.

The record from the external file is automatically inserted to the database.

Yes No Yes The record from the external file replaces the record in the database.


Yes Yes N/A The record from the external file updates the record in the 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.



10-7

• 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.



10-8

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 Field

Width

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 from the Object Designer.

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.



10-9

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.

8. Close the Properties window.



10-10

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.



10-11

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.


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.



10-12

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.


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.



10-13

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.


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.



10-14

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.



10-15

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.)

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 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 Manufacturing"

40 11

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.



10-16

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



10-17

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.

4. Close the Properties window, and compile, save and close the dataport.

5. Run table 90000, Vehicle, from the Object Designer. 6. Delete all the records in the table, and close the table. 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.



10-18

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 from the Object Designer.

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



10-19

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 Property

Remarks

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.



10-20

The following list explains more about Source Type options:

Source Type Value

Remarks

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.



10-21

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.



10-22

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 Property Value

Remarks

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.



10-23

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.



10-24

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 Of

Description

Format Option XMLport Determines the import/export format of the XMLport. The options are as follows: • XML • Variable Text • Fixed Text

Width Integer Nodes (elements and/or attributes)

Determines the width of the fixed width field. If Fixed Length is selected in 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>.



10-25

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.



10-26

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.)

3. Close the Properties window. 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.



10-27

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 Type

Source Type

Data Source

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.

8. Close the Properties window.



10-28

9. Compile and save the XMLport by clicking File, Save As. The Save As dialog box opens.

10. Type 90000 in the ID field and G/L Account Export XML in the Name field, ensure that the Compiled check box is selected, and 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."



10-29

6. Compile and save the codeunit by clicking File, Save As. TheSave As dialog box opens.

7. Type 90004 in the ID field and XML Export - G/L Account in the Name field, ensure that the Compiled check box is selected, and 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



10-30

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> <SerialNo>2000</SerialNo> <ListPrice>40,000</ListPrice> </Vehicle> <Vehicle> <Model>MAZDA</Model> <SerialNo>5500</SerialNo> <ListPrice>30,000</ListPrice> </Vehicle> <Vehicle> <Model>MAZDA</Model> <SerialNo>7500</SerialNo> <ListPrice>25,000</ListPrice> </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 XMLport Designer opens.

2. Open the Properties window for the XMLport and set the following 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.)



10-31


following:


Root Element Text



Node Name Node Type Source Type Data Source

Vehicle Element Table 90000

6. Go to the next line and type the following on the next few lines to

add several fields from the Vehicle table. Ensure that they are indented under the Vehicle element.


Data Source

Model Element Field Vehicle::Model

SerialNo Element Field Vehicle::Name

ListPrice Element Field Vehicle::List Price

7. Compile and save the XMLport by clicking File, Save As. The Save

As dialog box opens. 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.



10-32

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 As dialog box opens.

7. Type 90005 in the ID field and XML Import - Vehicle in the Name field, ensure that the Compiled check box is selected, and then click OK. This compiles and saves the codeunit.

8. Run table 90000, Vehicle, from the Object Designer.



10-33

9. Delete all the records in the table, and close the table. 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.



10-34

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.



10-35

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.

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 XMLport Action

4. Set the RunObject property of the action to XMLport G/L Account

Export XML. 5. Compile, save and close the page. Run the page and run the action.

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>

4. Close the Properties window, and compile, save and close the

XMLport. 5. Design page 90001, Custom Page, from the Object Designer. 6. Open the Action Designer for the page and type the following on the

empty line:

Caption Type Run XMLport Variable Text

Action

7. Set the RunObject property of the action to XMLport G/L Account

Export Variable. 8. Compile, save and close the page. Run the page and run the action.



10-36

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.



10-37

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 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: Variable Text (This specifies the external file to be an

XML document.) o FieldSeparator: , o FieldDelimiter: <None>


following:


Root Element Text



Node Name Node Type Source Type Data Source

Course Element Table 90010

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 Type

Source Type

Data Source

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



10-38

Node Name Node

Type Source Type

Data Source

Price Element Field Course::Price

Active Element Field Course::Active

Difficulty Element Field Course::Difficulty

PassingRate Element Field Course::Passing Rate

7. Compile and save the XMLport by clicking File, Save As. The Save

As dialog box opens. 8. Type 90010 in the ID field and Course Export Variable in the Name

field, ensure that the Compiled check box is selected, and then click 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

4. Close the Properties window, and compile, save and close the

XMLport.

Add actions in the Course List page to run the XMLports.

1. Design page 90011, Course List, from the Object Designer. 2. Open the Action Designer for the page. 3. Type the following on the empty line:

Type SubType

ActionContainer ActionItems



10-39

4. Type the following on the next lines and indent them under the ActionContainer.

Caption Type

Run XMLport Variable

Action

Run XMLport XML

Action

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. 7. Close the Properties window. 8. Compile, save and close the page.



10-40

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.



10-41

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?



10-42

Quick Interaction: Lessons Learned Take a moment and write down three key points you have learned from this chapter

1.

2.

3.


Na2009 enus devi_10

Technology

dataport properties

dataport components

dataport objects

dataport execution

dataport fundamentalsdataports

export data

dataport itselfand properties

data itemsthe data model