NAV Destination Component

Using the NAV Destination Component

The NAV Destination Component is an SSIS data flow pipeline component that can be used to write data to a destination Microsoft Dynamics NAV or Microsoft Dynamics 365 Business Central server. For the purpose of this documentation, Microsoft Dynamics 365 BC/NAV will refer to both Microsoft Dynamics 365 Business Central and Microsoft Dynamics NAV. You may Create, Update, Upsert, or Delete 365 BC/NAV records using the NAV Destination Component.

The NAV Destination Component includes the following three pages to configure how you want to write data to the Microsoft Dynamics 365 BC/NAV server.

• General
• Columns
• Error Handling

General Page

The General page of the NAV Destination Component allows you to specify general settings for the NAV destination component.

Select the connection manager and destination object

NAV Connection Manager

The NAV destination component requires a NAV connection in order to be able to connect to the Microsoft Dynamics 365 BC/NAV server. The NAV Connection Manager option will show all DynamicsNAV connection managers that have been created in the current SSIS package.

Action

The Action option allows you to specify how data should be written to the Microsoft Dynamics 365 BC/NAV server. There are currently four (4) supported action types available.

• Create: Create new record(s) in NAV
• Update: Update existing record(s) in NAV
• Delete: Delete record(s) from NAV
• Upsert: Query for record(s) with specific criteria, if there are matches an update will be performed; if there are no matches, the record(s) will be created in NAV.

Destination Object

The Destination Object option allows you to specify which 365 BC/NAV page or object to write data to.

Child Object

This option can be used In order to write Line items or child objects from your input data. To do so, you must map secondary inputs to the destination child objects using the Child Object settings. The table is only visible when the Destination Object contains Child Objects that you can write to. The 'Input' column will show all of the attached Secondary Inputs. The 'Child Entity' column will show drop-down lists of destination child objects. Select the child object that the secondary input represents and you will then be able to go to the Columns Page and edit the column mappings for that Secondary Input.

Multithreading and Batch Settings

Batch Size

The Batch Size option allows you to specify how many records you want to submit to the 365 BC/NAV web service.

Enable Multithreaded Writing (since v9.1)

Since the v9.1 release, we added support for the Multi-threading feature, which allows you to perform multi-threading when writing data to Dynamics 365 Business Central. To configure the Multi-threading feature, you can check the Enable Multithreaded Writing option in the NAV Destination component. The default number is 16.

Note: This option supports a maximum number of 100 threads when writing to Dynamics 365 Business Central. We generally recommend 20 or lower to avoid potential server errors. However, you can adjust these settings based on your environment in order to get the best performance.

Note: When this option is enabled, the record order may not be maintained from the upstream pipeline component.

Record Lookup/Matching Settings

Record Identifier

The Record Identifier option allows you to specify how the Update/Delete action determines whether a record already exists in the destination NAV system. In the case when Upsert action is used, this option will be automatically set to 'Manually Specified Keys' to specify how to find the matched records in NAV system to perform an Upsert operation. The component supports the following two matching options when the Update or Delete actions are selected.

• Primary Key: The Primary Key option matches NAV records based on the IDs of the primary keys.
• Manually Specified Keys: The Manually Specify option allows you to choose a combination of NAV fields to be used as matching criteria in order to determine whether a matching record exists in the NAV system. When the Manually Specify option is selected, you will see checkboxes next to the NAV fields in the grid on the Columns page.

Handling Multiple Matches

When the 'Manually Specified Keys' Record Identifier option is selected, It is possible that the component could find multiple matches in the target NAV system. The Handling of Multiple Matches option allows you to specify what action will be taken when such multiple matches are found. There are four options available.

• Write All Records: The component will write all records which share the same matching criteria.
• Write One Record: The component will write to only the first matching record.
• Ignore All Records: The source record will be ignored when multiple matches are found.
• Raise an Error: An exception will be reported when multiple matches are found.

Miscellaneous Settings

Ignore Null-Valued Fields

The Ignore Null-Valued Fields option allows you to ignore any fields that have a null value. By ignoring a field, the null value will not be posted to the NAV server.

Force to use ChangeSet

Enable this option to use ChangeSet. ChangeSet provides a way to bundle several operations that either succeed or fail as a group. When multiple operations are contained in a ChangeSet, all the operations are considered atomic, which means that if any one of the operations fails, any completed operations are rolled back.

Supplementary Parameters

When writing to specific objects (ex. General Journal object), special parameters are required. These input values will be specified in the Supplementary Parameters area. The general format looks something like this:

<CurrentJnlBatchName>CASH</CurrentJnlBatchName>

Refresh Component Button

Clicking the Refresh Component button causes the component to retrieve the latest metadata and update each field to its most recent metadata.

Map Unmapped Fields Button

By clicking this button, the component will try to map any unmapped NAV fields by matching their names with the input columns from upstream components. This is useful when your source component has recently added more columns, in which case you can use this button to automatically establish the association between input columns and unmapped NAV fields.

Clear All Mappings Button

By clicking this button, the component will reset all your mappings in the destination component.

Columns Page

The Columns page of the NAV Destination Component allows you to map the columns from upstream components to 365 BC/NAV fields for the destination entity.

On the Columns page, you would see a grid that contains three columns as shown below.

• Input Column: You can select an input column from an upstream component for the corresponding 365/NAV field.
• Destination NAV Field: The 365 BC/NAV field that you are writing data.
• Data Type: This column indicates the type of value for the current 365/NAV field in the 365/NAV system.

Note: if you hover over any OptionString Fields in the Destination NAV Field column, you will see all the possible OptionString fields that 365 BC/NAV will take as its input.

Error Handling Page

The Error Handling page allows you to specify how errors should be handled when they occur.

There are three options available:

1. Fail on error
2. Redirect rows to error output
3. Ignore error

When the Redirect rows to error output option is selected, rows that failed to write to Dynamics 365 BC/NAV will be redirected to the 'Dynamics NAV Destination Error Output' output of the Destination Component. As indicated in the screenshot below, the green or blue output connection represents rows that were successfully written, and the red 'Dynamics NAV Destination Error Output' connection represents rows that were erroneous. The 'NavErrorMessage' output column found in the 'Dynamics NAV Destination Error Output' may contain the error message that was reported by Dynamics 365/NAV or the component itself.

Note: Use extra caution when selecting Ignore error option, since the component will remain silent for any errors that have occurred.

On the Error Handling page, there is also an option (since v2.0) that can be used to enable or disable the following output fields for the destination component. Keep in mind that depending on the object selected, the key names will change.

• RecordKey.Document_Type: Contains the newly created 365/NAV record's Key, which you can use to write to log or further process using additional data flow components.
• RecordKey.No: Contains the newly created 365/NAV record's No field value. Note that this field may not be applicable to some entities or actions, in which case, the output will be just NULL.
• NavRecordNo
• IsNew: Contains value to indicate whether it is a newly created NAV record or an existing one. This is useful when you use the Upsert action.

Note: If you don't plan to use any of those fields for any further processing, it is generally recommended to turn them off, so you don't get any warning from SSIS by complaining that those fields are never used, and it should also provide slightly better performance by doing so. Note again this feature is only available since v2.0.