Alna Business, UAB

Lvovo str. 105A, Vilnius, Lithuania

LT-08104

Phone (8 5) 278 5500

Fax (8 5) 278 5511

E-mail info@alna.lt

Company code 300067906

VAT code LT100001324511

www.alnabusiness.lt

ALNA DOCUMENT IMPORT

User Manual

2

Table of Contents Alna Document Import ................................................................................................................................3

Data exchange definitions ..........................................................................................................................4

FastTab „General“ ..............................................................................................................................5

FastTab „Line Definitions“...................................................................................................................6

Field mapping .....................................................................................................................................7

FastTab „Column Definitions“ .............................................................................................................8

Document import definitions .................................................................................................................... 10

FastTab „General“ ........................................................................................................................... 11

FastTab „Document import fields mapping” .................................................................................... 11

3.2.1. Fields value mapping .................................................................................................................. 12

3.2.2. Document import rules ............................................................................................................... 12

FastTabs „Default accounts” and „Background Importing” .............................................................. 13

Custom Source setup ...................................................................................................................... 14

Document import register ........................................................................................................................ 16

Document import ............................................................................................................................. 16

Correction of Errors ......................................................................................................................... 18

Local dimensions mapping ...................................................................................................................... 18

CodeUnit/ XMLport table ......................................................................................................................... 19

Picture list ................................................................................................................................................ 20

3

Alna Document Import

Alna Document Import – apps dedicated for sales and purchase document import from .csv .txt and .xml format file. There are three main parts of Alna Document Import:

1. Data exchange definitions – standard Dynamics 365 Business Central functionality part for

system table and fields with file information mapping.

2. Document import definitions – functionality part for additional rules.

3. Document import register – functionality part for file import.

4

Data exchange definitions

First, you need to create a data exchange definition for data file.

You can find Data exchange definitions page on search:

Picture 1 Data Exchange Definitions

You can assign one data file structure to one data exchange definition.

Choose in actions to open page for new data exchange definition.

There are three FastTabs in data exchange definitions page.

5

FastTab „General“

On the General FastTab, describe the data exchange definition and the data file type by filling the fields:

Picture 2 Data Exchange Definitions, FastTab „General “(CSV file type)

1. Code – Enter a code to identify the data exchange definition. 2. Name – Enter a name for the data exchange definition. 3. File type – Specify what type of file that the data exchange definition is used for. You can select between

three file types: a. XML - for .xml file format b. Variable text - for .csv or .txt file import. Records have variable length and are separated by a

character, such as comma or semi-colon. Also known as delimited file. c. Fixed text - for.csv or .txt file import. Records have the same length, using pad characters, and

each record is on a separate line. Also known as fixed-width file. 1. Data handling codeunit, Validation codeunit, Reading/Writing Codeunit, Reading/Writing

XMLport, Ext. Data Handling Codeunit, User Feedback Codeunit – Enter values from

CodeUnit/XMLport table.

4. File Encoding – Specify the encoding of the file. 5. Column Separator – Specify how columns in the data file are separated, if the file is of Variable Text

type. 6. Header Lines – Specify how many header lines exist in the file. This ensures that the header data is

not imported. Header Tag - If a header line exists in several positions in the file, enter the text of the first column on the header line.This ensures that the header data is not imported.

6

7. Footer Tag - If a footer line exists in several positions in the file, enter the text of the first column on the footer line. This ensures that the footer data is not imported.

Picture 3 Data Exchange Definitions, FastTab „General “(XML file type)

FastTab „Line Definitions“

On the Line Definitions FastTab, describe the formatting of lines in the data file by filling the fields as described

in the following list. For import, you need to create a line for document header and document line.

Picture 4 Data Exchange Definitions, FastTab „Line definitions “(CSV file type)

1. Line type – Select between Header and Detail. 2. Code – Enter a code to identify the line in the file. 3. Name – Enter a name that describes the line in the file. 4. Column Count – Specify how many columns the line in data file has. Note: This field is only

relevant for import. 5. Data Line Tag – Specify the position in the related XML schema of the element that represents

the main entry of the data file. Note: This field is only relevant for import. 6. Namespace – Specify the namespace that is expected in the file, to enable namespace

validation

Picture 5 Data Exchange Definitions, FastTab „Line definitions “(XML file type)

7

Field mapping

On the Line Definitions FastTab, select the line for which you want to map columns to fields, and then choose

Field Mapping:

Picture 6 Data Exchange Definitions, Field mapping

The Data Exchange Mapping page opens. On the FastTabs, specify the mapping setup by filling the fields as

described in the following list:

Picture 7 Data Exchange Definitions, fields mapping page

FastTab „General“:

1. Table ID – Specify the value from Codeunit/XMLport table

2. Use as Intermediate Table – Mark „“.

3. Name – Enter a name for the mapping setup.

4. Pre-Mapping Codeunit – Specify the value from Codeunit/XMLport table

5. Mapping Codeunit – Specify the value from Codeunit/XMLport table

6. Post-Mapping Codeunit - Specify the value from Codeunit/XMLport table

FastTab „Field Mapping“: 1. Column No. – Specify which column in the data file that you want to define a map for. 2. Field ID – Specify which field the column in the Column No. field maps to. 3. Target Table ID – Specify the table that the value in the Column Caption field is mapped to, when you

are using an intermediate table for data import. 4. Target Table Caption – Specify the name of the table in the Target Table ID field, which is the table

that the value in the Column Caption field is mapped to, when you are using an intermediate table for data import.

5. Target Field ID – Specify the field in the target table that the value in the Column Caption field is mapped to, when you are using an intermediate table for data import.

6. Target Field Caption – Specify the name of the field in the target table that the value in the Column Caption field is mapped to, when you are using an intermediate table for data import.

7. Optional – Specify that the map will be skipped if the field is empty. 8. Transformation rule – According to the need, specify the data transformation rule.

8

FastTab „Column Definitions“

On the Column Definitions FastTab, choose Get File Structure.

Picture 8 Manage, Get file structure

On the Get File Structure page, select the related structure file and path, and then choose the OK button. The

lines on the Column Definitions FastTab are filled according to the structure of the data file:

Picture 9 Data Exchange Definitions „Get File Structure“

For CSV/txt file type describe the formatting of columns in the data file by filling the fields on the Column

Definitions FastTab.

1. Column No. – Specify the number that reflects the column’s position on the line in the file.

2. Name – Specify the name of the column.

3. Description – Enter a description of the column, for information.

4. Constant – Specify any data that you want to export in this column, such as extra information about

the payment type.

Picture 10 Data Exchange Definitions, FastTab „Column definitions “(CSV file type)

9

For XML file type describe the formatting of columns in the data file by filling the fields on the Column

Definitions FastTab.

1. Column No. – Specify the number that reflects the column’s position on the line in the file.

2. Name – Specify the name of the column.

3. Description – Enter a description of the column, for information.

4. Path - Specify the position of the element in the related XML schema.

5. Constant - Specify any data that you want to export in this column, such as extra information about

the payment type.

Picture 11 Data Exchange Definitions, FastTab „Column definitions “(XML file type)

For more information about Data Exchange Definitions click link below: https://docs.microsoft.com/en-

us/dynamics365/business-central/across-how-to-set-up-data-exchange-definitions

10

Document import definitions

Each data exchange definition needs to have one document import definition. You can specify additional rules

in the document import definition page. Additional rules – rules for modifying your data or adding some

information from your system to imported document (example: dimensions).

You can find document import definitions page on search:

Picture 12 Document import definitions

Choose in actions to open a blank page for document import.

There are import and export buttons in the actions. You can transfer your document import definition from one

company to another or from testing database to live database.

Picture 13 Document import definitions import/export

11

Also you can find button “New Import from File” in the actions for importing data file to system. There is another

way to import data file, read chapter Document import register.

Picture 14 Document import definitions import from file

FastTab „General“

On the “General” FastTab describe the values by filling these fields:

1. Code – Enter a code to identify the document import definition.

2. Name – Enter a name that describes document import definition.

3. Data Exchange Definition Code – Choose the data exchange definition from the list.

4. Data Source Handling CodeUnit – Specify the value from Codeunit/XMLport table.

5. Skip duplicates by Document No. - If selected all documents with the same document no. value are

skipped.

6. Skip duplicates by External Document No. - If selected all documents with the same External

document no. value are skipped.

Picture 15 Document import definitions FastTab “General”

FastTab „Document import fields mapping”

On the “Document Import Fields Mapping” FastTab you can see all data from your specified data exchange

definition and fields values map table. On this FastTab you can specify local dimensions, read more in chapter

“Local dimensions mapping”.

Picture 16 Document import definitions, FastTab “Document import fields mapping”

12

3.2.1. Fields value mapping

Choose “Fields Value Mapping” on Document Import Field Mapping actions. This is additional table for value

replacing. This table needs to be use then value in file do not match value in system, for example: document

type value in file is “SF”, but system requires document type value “Invoice”. Values, which you specify in this

table, will be replaced during the import process.

Picture 17 Document import definitions,Manage, Fields value mapping

Picture 18 Document import definitions, Fields value mapping

3.2.2. Document import rules

On the FastTab “Doc. Imp. Condition Stmt. Part” fill Line no. field, then press “Show Condition” in actions. If you

already have rules defined then you can copy it with “Copy Condition Statement” button in actions.

Picture 19 Document import definitions, “Doc. Imp. Condition Stmt. Part”

13

First, specify description in open page. Then you can specify rules:

Condition have three parts: IF; THEN; ELSE.

On the “Doc. Import Condition Line” FastTab specify Data Exch. Line Definition, Column no. Relational Operator,

Expression and Logical operator. This is part of the condition “IF”. For example, if Currency code is EUR or

USD.

On the “Doc. Imp. True Condition Stmt,” FastTab specify Data Exch. Line Definition, Column no. Action,

Expression. This is part of the condition “THEN”. For example, Then due date is “C” (Current).

On the “Doc. Imp. False Condition Stmt,” FastTab specify Data Exch. Line Definition, Column no. Action,

Expression. This is part of the condition “ELSE”. For example, Else do nothing.

The full example: IF currency code is EUR or USD, then set current date on due date, else do nothing.

Picture 20 Document import definitions, Making Rules

Possible actions:

1. Set value to – replace to value specified in the “Expression” field.

2. Save value to memory – copy value from field to memory.

3. Set value from memory – paste value from memory

4. Multiply – the number is multiplied by the number specified in the "Expression" field.

5. Divide – the number is divided by the number specified in the "Expression" field.

6. Add – the number is added to the number specified in the "Expression" field.

7. Subtract – the number is subtracted from the number specified in the "Expression" field.

FastTabs „Default accounts” and „Background Importing”

On the “Default Accounts” FastTab specify the general ledger accounts for not found values.

Also, specify unrecognized customer or vendor action:

1. Error – document will not be created if customer is not found in the system.

2. Default – if customer is not found, field will be filled in with the „Default customer“ code.

3. New from template – the customer or vendor card will be created from the customer or vendor

template. If you choose this action, you need to set value in field “New Customer Template” or “New

14

Vendor Template”. To create customer or vendor you need to specify at least one of the required field

(for example, customer name or address) in data exchange definitions page.

Picture 21 Document import definitions, FastTab „Default accounts “

On the “Background Import” FastTab mark field “Import with Job Queue” to import file at a specific time and

date.

Picture 22 Document import definitions, FastTab „Background Importing “

Custom Source setup

You can setup custom fields for recognizing customer or vendor. Choose “Custom Source Search Fields“ to

open setup page:

Picture 23 Actions, Customer Source Search Fields

Describe the values by filling these fields:

1. Source Type – choose “Customer” or “Vendor”.

15

2. Source Field Id – specify a value from fields list to recognize “Sell-to Customer”/”Buy-from Vendor”.

3. Source Field Caption – specify the name of the field in the Source Field Id field. 4. Document Field Id - specify a value from fields list to recognize “Bill-to Customer”/”Pay-to Vendor”.

5. Document Field Caption - specify the name of the field in the Document Field Id field.

If “Sell-to Customer”/”Buy-from Vendor” and “Bill-to Customer”/”Pay-to Vendor” are the same, you don’t have to

specify field “Document Field Id.

Picture 24 Document import definitios, Custom Source Search Fields

16

Document import register

Document import

In Document import Registers page you can import your data file.

Picture 25 Document Import Register

Choose in actions.

17

Picture 26 Document import register, FastTab „General “

1. Choose Import Definition from list.

2. Choose in actions and choose a file for import.

3. Choose in actions.

Imported documents can be found on the “Document preview” FastTab. If document does not have errors, you

can find it in sales or purchase document list. If document has errors, it is not created yet.

Picture 27 Document import register, FastTab „Document preview “

Errors and warnings field specifies how many errors your document has. Click on number for details. Status field specifies status of document. Choose “Preview document” in actions to preview document. Choose “Open Created Document” in actions to open the created document.

There are few functions for identifying errors:

1. Choose in actions to

open page for file details.

18

2. Find the “Errors and Warnings” FastTab to identify file errors.

3. Choose “Open Related Record” to open table of error source (for example, if you have error “Cannot

find an appropriate G/L account” then chart of accounts is opened). Not all errors have related

records.

4. Choose View Details in actions to open detail error page.

Picture 28 Document import register, FastTab „Errors and Warnings “

Correction of Errors

If document is imported without errors, it can be checked and posted.

If document is not imported due to errors, the following steps are needed:

1. If there is an error in the Dynamics 365 Business Central system (for example, the unit of mesure

could not be found) – enter the missing data and press "Load file data“ in the same document import

register.

2. If an error occurs due to incorrect data exchange definition or document import definition of the import

description, correct the definition and import the file again. (Note: if you marked check box in

document import definitions “Skip duplicates“, the already created documents will not be created for

the second time).

3. If an error is in the data file, you need to correct it and import file again. (Note: if you marked check

box in document import definitions “Skip duplicates“, the already created documents will not be

created for the second time).

Local dimensions mapping

If you want to import local dimensions, you need to setup file field to Dynamics 365 Business Central table 349

field 2. Only then, document import definitions column “Dimension Code” will be editable. In this field, choose

your dimension.

19

CodeUnit/ XMLport table

Data exchange definitions: XML Variable text

Data Handling Codeunit 17007204 17007204

Validation Codeunit 0 0

Reading/Writing Codeunit 1203 0

Reading/Writing XMLport 0 17007200

Ext. Data Handling Codeunit 0 0

User Feedback Codeunit 0 0

Fields mapping (Header): Table ID 17007209 17007209

Pre-Mapping Codeunit 17007202 17007202

Mapping Codeunit 17007203 17007203

Post-Mapping Codeunit 0 0

Fields mapping (Lines): Table ID 17007209 0 Pre-Mapping Codeunit 0 0 Mapping Codeunit 0 0

Post-Mapping Codeunit 0 0

Document import definitions Data Source Handling Codeunit 17007211 17007211

20

Picture list

Picture 1 Data Exchange Definitions .........................................................................................................4 Picture 2 Data Exchange Definitions, FastTab „General “(CSV file type) .................................................5 Picture 3 Data Exchange Definitions, FastTab „General “(XML file type) .................................................6 Picture 4 Data Exchange Definitions, FastTab „Line definitions “(CSV file type) ......................................6 Picture 5 Data Exchange Definitions, FastTab „Line definitions “(XML file type) ......................................6 Picture 6 Data Exchange Definitions, Field mapping .................................................................................7 Picture 7 Data Exchange Definitions, fields mapping page .......................................................................7 Picture 8 Manage, Get file structure ...........................................................................................................8 Picture 9 Data Exchange Definitions „Get File Structure“ ..........................................................................8 Picture 10 Data Exchange Definitions, FastTab „Column definitions “(CSV file type) ...............................8 Picture 11 Data Exchange Definitions, FastTab „Column definitions “(XML file type) ...............................9 Picture 12 Document import definitions .................................................................................................. 10 Picture 13 Document import definitions import/export ............................................................................ 10 Picture 14 Document import definitions import from file.......................................................................... 11 Picture 15 Document import definitions FastTab “General” .................................................................... 11 Picture 16 Document import definitions, FastTab “Document import fields mapping” ............................ 11 Picture 17 Document import definitions,Manage, Fields value mapping ................................................ 12 Picture 18 Document import definitions, Fields value mapping .............................................................. 12 Picture 19 Document import definitions, “Doc. Imp. Condition Stmt. Part” ............................................. 12 Picture 20 Document import definitions, Making Rules........................................................................... 13 Picture 21 Document import definitions, FastTab „Default accounts “ .................................................... 14 Picture 22 Document import definitions, FastTab „Background Importing “ ........................................... 14 Picture 23 Actions, Customer Source Search Fields .............................................................................. 14 Picture 24 Document import definitios, Custom Source Search Fields .................................................. 15 Picture 25 Document Import Register ..................................................................................................... 16 Picture 26 Document import register, FastTab „General “ ...................................................................... 17 Picture 27 Document import register, FastTab „Document preview “ ..................................................... 17 Picture 28 Document import register, FastTab „Errors and Warnings “ .................................................. 18