---
title: "Set up Database connector"
slug: "set-up-database-connector-data-migration"
description: "Connect to external databases using ODBC connections in D365 F&SCM. Learn to set up and manage database connectors effectively."
tags: ["Task topic"]
status: "update"
updated: 2026-10-05T12:00:08Z
published: 2026-10-05T12:00:08Z
canonical: "docs.staedean.com/set-up-database-connector-data-migration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staedean.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Database connector

Set up a connector of type **Database**. Use this type to directly connect to an external database. This external database can be an on-premises database or a cloud database.

You can connect to an external database with an:

- ODBC connection: Connects to an external database via ODBC, using an Azure Service Bus. If you connect to an external database via ODBC and you run D365 F&SCM:
  - In the cloud, use an Azure Service Bus to connect to the external database.
  - On-premises, you can connect to the external database without an Azure Service Bus.
  - On-premises, you can also connect without an Azure Service Bus and additionally use Direct SQL to export data to the external database
- SQL connection: Connects to an external Azure SQL database.

### Steps

1. Click **Connectivity studio - Integration Design**.
2. Click the **Connectors** tab.
3. Click **New**.
4. In the **Connector** field, type a value.

> [!NOTE]
> **Note**
> 
> You are advised to not include, in the connector name, the name of the application to which you connect. Use the **Application** field to define the applicable application for the connector.
5. In the **Project** field, enter or select a value.
6. Define the applicable application for the connector. For a **Database** connector, for example, select an '**ODBC'**, '**SQL**', or '**ERP**' application.

In the **Application** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> - You can only select an application that is defined for the applicable project. You can define project applications on the **Projects** page.
> - You can type any existing application name, whether it is defined as project application or not. If the typed application is not defined as project application, it is automatically added to the project applications.
7. In the **Connector type** field, select '**Database**'.
8. Click **Save**.
9. Sub-task: Set properties.
  1. Expand the **Properties of Test** section.
  2. You can export connectivity setup and import it in another D365 F&SCM environment. For example, you first set up and test the connectivity setup in a development environment. When finished, you deploy the setup in your production environment. To prevent messing up your production data, use different file locations for your development or testing environment and for your production environment. To strictly distinguish between different environments, you can define unique connector properties for each of your environment types. So, each connector can have a different set of properties for each applicable environment type. Which connector properties are applicable to the current environment is defined in the **Environment type** field on the **Connectivity studio parameters**. **Example**: If set to **Development**, the connector properties, as defined for environment type **Development** are applicable. In the **Environment types** field, select an option.

> [!NOTE]
> **Note**
> 
> The environment types only apply to connectors of type **Database**, **Azure file storage**, **Blob storage**, **SharePoint**, or **Service Bus queue**.
  3. In the **Windows Azure Service Bus namespace** field, enter the primary connection string of the created Azure Service Bus namespace.

> [!NOTE]
> **Note**
> 
> This field is only applicable if you run D365 F&SCM in the cloud and you use an ODBC connection. If you use Connectivity Studio on a D365 F&SCM (on-premises) environment, you can directly connect to another on-premises SQL server database. In this case, you do not need the Azure Service Bus for Database connector setup.
  4. Define the primary key or the primary key reference to access the Azure Service Bus namespace. Whether the primary key or primary key reference applies is defined by the **Display secret** field in the **Connectivity studio parameters**.

If the **Display secret** parameter is set to:

In the **Service Bus key** field, or in the **Service Bus key reference** field, type a value.

> [!NOTE]
> **Note**
> 
> This field is only applicable if you run D365 F&SCM in the cloud and you use an ODBC connection.
    - **Secret**, fill in the **Service Bus key** field with the desired primary key. The primary key is specific for the current connector.
    - **Secret reference**, fill in the **Service Bus key reference** field with the desired primary key reference. The primary key reference refers to a centrally stored primary key which makes updating secrets easier.
    - **Both**, fill in either the **Service Bus key** field or the **Service Bus key reference** field.
  5. Define how you want to connect to an external database:

In the **Database connection** field, select an option.
    - **ODBC connection**: Connects to an external database via ODBC, using an Azure Service Bus.
    - **SQL connection**: Connects to an external Azure SQL database.
  6. In the **Data source name** field, enter the data source name (DSN) as created on the external on-premise server.

> [!NOTE]
> **Note**
> 
> - This field is only required for an **ODBC connection**.
> - The ODBC connection string, that is used to connect to the ODBC database, is shown in the **Connection string** field. The connection string is created based on the settings in the ODBC data source and Direct SQL properties.
  7. If the connection type is:

In the **Operator name** field, type a value.

> [!NOTE]
> **Note**
> 
> For an ODBC connection:
> 
> - This operator and password are only applied if no **Login ID** and **Password** are defined for the DSN.
> - If you do not define a login ID and password here, make sure the **Login ID** and **Password** are defined on the DSN.
    - **ODBC**, you can define the login ID to be used to connect to the data source name (DSN) as created on the on-premises server.
    - **SQL**, define the login ID to be used to connect to the Azure SQL database,
  8. Define the password or the password reference to connect:

Whether the password or password reference applies is defined by the **Display secret** field in the **Connectivity studio parameters**. If the **Display secret** parameter is set to:

    - **Secret**, fill in the **Password** field with the desired password. The password is specific for the current file action.
    - **Secret reference**, fill in the **Password reference** field with the desired secret reference. The password reference refers to a centrally stored password which makes updating secrets easier.
    - **Both**, fill in either the **Password** field or the **Password reference** field.

In the **Password** field or in the **Password reference** field, type a value.
    - For **ODBC**, the data source name (DSN) as created on the on-premise server.
    - For **SQL**, the Azure SQL database.
  9. For a Database connector, you can configure a timeout. If an export or import exceeds the specified time, the process is stopped and a timeout error is returned. The timeout value is expressed in seconds. In the **Timeout (secs)** field, enter the timeout threshold in seconds.

> [!NOTE]
> Note
> 
> This timeout is related to the **Service Bus** **Timeout** as defined in the **Connectivity Studio parameters**. When both timeout settings are configured, the higher value of the two is applied.
  10. If you use Connectivity Studio on a D365 F&SCM (on-premises) environment, you can directly connect to another on-premises SQL server database with direct SQL. You can use this connection only to export data from a D365 F&SCM (on-premises) database.

If you use direct SQL, you must define the linked server instance.

In the **Linked server instance** field, enter the name of the linked server instance that is defined on the SQL server instance to connect to the D365 F&SCM database.

> [!NOTE]
> **Note**
> 
> This field is only required for an ODBC connection.
  11. If you use an ODBC connection with direct SQL, instead of the **Data source name**, you can define the:

In this case, you connect to the external database using the driver instead of the DSN. See also the connection string.

If you use an SQL connection, always define the **Database server name** and **Database name**.

In the **Database server name** field, enter the SQL server instance name.
    - **Database server name**
    - **Database name**
  12. In the **Database name** field, enter the name of the applicable database on the defined SQL server instance.
  13. Usually, the data source name (DSN) is used to connect to the external database. However, if you use direct SQL, you can connect using the driver.

By default the 'SQL Server Native Client 11.0' ODBC driver is used. You can define another, ODBC driver.

Example: 'ODBC Driver 13 for SQL Server'.

In the **ODBC driver** field, type a value.

> [!NOTE]
> **Note**
> 
> This field is only required for an ODBC connection.
  14. By default, an automatically composed connection string is shown. You cannot change this connection string.

If you need to change the connection string, you can choose for a **Customized connection string**.

Select **Yes** in the **Customized connection** field.
  15. When you enable the **Customized connection string**, the default connection string is shown. You can change this connection string as desired.

In the connection string, you can use these connector properties:

In the **Customized connection string** field, make the desired changes.
    - %1 - Database server name
    - %2 - Database name
    - %3 - Data source name
    - %4 - Operator name
    - %5 - Secret
    - %6 - Time out
    - %7 - ODBC driver
    - %8 - ODBCAdditionalSetup (This is a hidden property that you can add to the form.)
10. Sub-task: Select custom handler.
  1. Expand the **Custom** section.
  2. For a **Database** type connector, the standard handler class is **BisConnectorODBC**. This handler class exports data to or imports data from an external database.

You can use a customized handler class. To do so, extend the standard handler class.

In the **Handler** field, you can enter or select a custom handler class.
11. Sub-task: Define company range.
  1. You can import or export data for the current D365 F&SCM company only. To do so, define the company range.

In import or export of data, the current company in D365 F&SCM is used.

If you do not define the company range, data is imported or exported for all companies in the D365 F&SCM environment.

Expand the **Company range** section.

> [!NOTE]
> **Note**
> 
> The field name of the company field in **D365 F&SCM** is '**DataAreaId**'.
  2. In the **Field name** field, enter the name of the company field in the on-premises server database.
  3. If the company names in the on-premises server database are different from the D365 F&SCM company names, define the applicable transformations. In a transformation, you can define which on-premises company name corresponds with which D365 F&SCM company name.

In the **Transformation** field, enter or select a value.
  4. Define the field type of the company field in the external database.

In the **Type** field, select an option.
  5. In database systems, such as Microsoft Dynamics AX 2012 R2 and later, data partitions are used to logically separate data within a single database. To be able to use the primary index in your query, the partition is now included in the database (ODBC) query. The partition column in each AX 2012 table (usually called PARTITION) stores the RecId of an entry in the **Partitions** table.

In the **Partition** field, enter the partition column name.
  6. In AX 2012, several partitions can exist. Define the desired partition for your query.

In the **Partition value** field, enter the RecId of the desired partition.

> [!NOTE]
> Note
> 
> Besides the **Partition**, the primary index of AX 2012 tables also includes the **Data area ID**. The connector uses the current legal entity's **Data area ID** automatically.
12. Sub-task: Set advanced options.
  1. Expand the **Advanced options** section.
  2. A document can have a query for which cross-company is enabled. If a user, with access to a restricted set of companies, runs a message that uses the document, the cross-company option does not work. If you have this scenario, make sure the cross-company option is enabled for the used connector. Otherwise, you can disable the cross-company option.

Select **Yes** in the **Cross company disabled** field.
13. Close the page.

> [!NOTE]
> **Notes**
> 
> - You can test the connection. To do so, on the **Connectors** page, in the **Action Pane**, on the **Development** tab, click **Test connection**.
> - You can change the type of an existing connector. If you do so, also fill in the applicable fields. For more information, refer to the topic about the setup of the newly chosen connector type.
> - For both the ODBC connection and the SQL connection, these data type are not supported: time, timestamp, binary, varbinary, sql_variant, datatimeoffset.

## Related

- [Set up Azure Relay for Database connection](/set-up-azure-relay-for-database-connection-data-migration.md)
- [Customize connector handler class](/customize-connector-handler-class.md)
- [Set up secret references](/set-up-secret-references.md)