Dataports enable you to import data from external text files to the Microsoft Dynamics NAV database and export data from the Microsoft Dynamics NAV database to text files in cases where XML is not supported. For all other cases, use XMLports instead. For more information, see Creating XMLports.
A dataport is an object. There is a wide range of options for defining the format of the external file while you are importing and exporting the object. You design dataports in Dataport Designer, which you open from Object Designer.
Note |
---|
Application Server for Microsoft Dynamics NAV does not support dataports. |
Defining Dataports
A dataport object defines the data that must be exported from or imported into the Microsoft Dynamics NAV database. When you are importing data, you can control what happens if a record in the file being imported has the same value in the key as an existing record in the database table. In addition, at field level, you can control if the OnValidate trigger for each field should be run.
Dataports can be dynamic, meaning that when you execute the dataport, you specify if it must import or export data, and you specify the name of the file to read from or write to. This can be achieved either by defining options that the user sets in the request form or by programming.
Dataports can be run without user interaction.
Logical Design
Designing a dataport involves two distinct tasks:
-
Designing the data model.
-
Defining the layout of the external file.
Designing the Data Model
You build the data model by designing data items. A data item corresponds to a table.
When you are exporting data, each data item is iterated for all the records in the underlying table, and you can set up sort order, keys, and table views to use. You can decide whether each record should be written to the external file.
When you are importing data, the records read from the external file can be inserted into tables that correspond to the data items. You can examine the records before inserting them and you can specify:
-
If the records should be inserted.
-
If the records should be inserted automatically.
-
If the records that are already in the database should be overwritten or updated when a record with the same primary key is read from the external file.
For more information, see Designing Dataports.
Designing the External File
The layout of the external file is defined by means of a set of dataport properties. When you are importing, these properties describe how the input stream should be broken up into records and fields. When you are exporting, these properties describe how the fields and records should be written to the file.
The properties that you can set vary depending on the format of the external file.
For more information, see Designing Dataports.
Saving, Compiling, and Running a Dataport
After you have designed a dataport, you must save and compile it before it can be run. Usually, you do this when you have finished designing the dataport. However, you may want to save a dataport that is not yet finished and therefore cannot be compiled. For more information, see How to: Save a Dataport. You can also test-compile a dataport without closing or saving it. For more information, see How to: Compile a Dataport.
Running Dataports
When a dataport runs, various triggers execute C/AL functions. The following illustration shows the flow of running a dataport.
The following list describes the steps needed to run a dataport.
-
When you start the dataport run, the OnInitDataport trigger is run.
Note Use this trigger to initialize variables but not for general processing purposes.
-
When the OnInitDataport trigger has been executed, the request form for the dataport is run, if it is defined. You can cancel the dataport run from the request form.
-
If you choose to continue, the dataport enters a transaction by issuing a Begin Write Transaction (BWT), and then the OnPreDataport trigger is called. No data has been processed at this stage.
-
The OnPreDataport trigger can be used to process the user input from the request form.
-
When the OnPreDataport trigger has been executed, the external file is opened, and the processing of the first data item begins.
-
When the first data item has been processed, the next data item, if there is one, is processed in the same way.
-
When there are no more data items, the OnPostDataport trigger is called. You can use this trigger to do any post processing that is necessary.
-
When the OnPostDataport has been processed, the external file is closed.
-
The transaction that was entered in step 3 ends with an End Write Transaction (EWT) being issued.
The processing of each data item (steps 5 and 6) is, of course, different for importing and exporting. However, the entire processing of a dataport takes place within a transaction. This means that if the processing is interrupted before the final EWT is issued, no trace is left of the interrupted run in the database, but an external file will often have been corrupted.