---
title: "Set up message"
slug: "set-up-message"
description: "Learn how to set up message headers for data transport, defining source and target connectors, documents, and settings for efficient integration."
updated: 2026-07-15T09:21:40Z
published: 2026-07-15T09:21:40Z
canonical: "docs.staedean.com/set-up-message"
---

> ## 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 message

Use messages as the carriers that transport data from a source to a target, based on the mapping as defined on the message.

This topic explains how to set up a message header. On a message header you define:

- The source information: the connector and document that is used for the data source.
- The target information: the connector and document that is used for the data target.
- General settings that define the behavior of the message.

### Steps

1. Click **Connectivity** **studio - Integration Design**.
2. Click **New**.
3. Define a meaningful name for the message. **Example:** If the message is used for a sales integration, you can use names like 'Sales - Orders' or 'Sales - Invoices'.

In the **Message** field, type a value.
4. Define the project to make the message unique. You can, for example, use a project to combine all messages with the same purpose. So, for example, you can combine all warehousing inbound related messages in the same project.

In the **Project** field, enter or select a value.
5. Define the connector that connects to the data source.

In the **Source connector** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> You can only select a connector that is defined for the applicable project.
6. Define the document that defines which data you want to get from the data source and in which format and structure.

In the **Source document** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> - You can only select a document that is defined for the applicable project and that is linked to the same application as the source connector.
> - Make sure the source connector and source document have a compatible handler version. For example, if you use a source connector of type **Web service**, **Blob storage**, or **Upload and download**, the handler version of the related source document must be 'V3'.
7. Define the connector that connects to the data target.

In the **Target connector** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> You can only select a connector that is defined for the applicable project.
8. Define the document that defines which data you want to move to the data target and in which format and structure.

In the **Target document** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> - You can only select a document that is defined for the applicable project and that is linked to the same application as the target connector.
> - Make sure the target connector and target document have a compatible handler version. For example, if you use a target connector of type **Web service**, **Blob storage**, or **Upload and download**, the handler version of the related target document must be 'V3'.
9. Sub-task: Define history settings.
  1. Expand the **History** section.
  2. Select what is stored in the history:
    - **History**: Only generic message errors are stored in the history for the message.
    - **Record history**: Record-specific message errors are stored in history for the message. The record details are added to the history as well. In the **History type** field, select an option.
  3. Define the transaction level for the message. You can choose these levels:
    - **Root record**: For a message run, the data is processed in separate transactions per root record entity of the document. For example, if you process several sales orders in one message run, each sales order and related data is processed in a separate transaction.
    - **Document**: For a message run, all data is processed in one transaction. For example, if you process several sales orders in one message run, all sales orders are processed in the same transaction.

> [!NOTE]
> **Note**
> 
> You are advised to thoroughly consider the number of records to be processed in one transaction. If you process a large number of records in one transaction, and one of these records fail, none of the records is processed.

In the **Transaction level** field, select an option.
  4. You can create a report in Microsoft Excel format that contains the errors that occurred during a message run. You can, for example, use this to inform the sender of data on the errors. The report is created when the message run is finished. The report is stored in the folder as defined in the **Connectivity studio parameters**, in the **History report path** field.

Select **Yes** in the **Create history report** field.
  5. By default, only the records with errors are stored. You can also store the successfully processed records in the history.

Select **Yes** in the **Store history** field.

> [!NOTE]
> **Note**
> 
> Usually, you only store history when you test a message.
  6. On import, you can log which D365 F&SCM data is changed during import. Changes are logged by field. Only the latest change is stored for each field.

Select **Yes** in the **Log changes** field.

> [!NOTE]
> **Note**
> 
> Usually, you only log changes when you test a message.
10. Sub-task: Define company-change settings.
  1. During import, you can switch to a different company if a source file has records that must be imported into different companies. You can only do so if the transaction level is **Root record**.

Expand the **Change company** section.
  2. Define the field of the root record of the source document that represents the company ID. As a result, before a new database transaction is created for the root record, the import is switched to the company as defined in the root record.

In the **Source field** field, enter or select a value.
  3. If company identifications from the source document differ from the company IDs in D365 F&SCM, you can apply a transformation. Select the transformation that defines which source company identification maps to which D365 F&SCM company ID.

In the **Transformation** field, enter or select a value.
11. Sub-task: Define source-status update settings.
  1. Expand the **Update source status** section.
  2. You can change the status of a source record in:

D365 F&SCM if you export data from D365 F&SCM with an internal document as source document. In this case, indicate which of the root record table fields represents the record status.

An external database if you import data via ODBC or from an Azure SQL database (source document must be of type ODBC and connector must be of type Database). In this case, indicate which of the root record external table fields represents the record status.

In the **Status** **field** field, enter or select a value.
  3. Enter the status that is assigned to a record if the message is successfully processed.

In the **Processed status** field, type a value.
  4. Enter the status that is assigned to a record if errors occurred on processing the message.

In the **Error status** field, type a value.
12. Sub-task: Define performance-related settings.
  1. You can use the D365 F&SCM batch processing to improve the performance by running batch tasks in parallel.

Expand the **Performance** section.
  2. You can define how batch tasks are run when a message is processed. If the type is:

In the **Type** field, select an option.

> [!NOTE]
> **Note**
> 
> Parallel processing is only applied if the message is run in batch.
    - **Sequential**, batch tasks are processed in the defined sequence (files) or in the creation sequence (paging).
    - **Parallel**, batch tasks are split over several threads to run in parallel. Parallel processing improves the performance of message processing.
  3. If the source document is an external file-based document, and the performance type is **Sequential**, define the sequence in which the files are processed.

In the **File selection sort order** field, select an option.

> [!NOTE]
> **Note**
> 
> This field is only applicable if the source document is an external file-based document.
  4. If Parallel processing is applied, by default the number of threads is set to 0. When the message is run, for each file to be processed a separate batch task is added to the batch job.

> [!NOTE]
> **Disadvantage**
> 
> The more files must be processed, the more batch tasks are created. This can 'flood' the batch system with batch tasks being run at the same time.

You can define a number of threads to limit the number of batch tasks that are created for a message run. As a result, the files to be processed are spread over the defined number of threads.

**Example:** Threads number is 5, number of files is 50. Five batch tasks are created, each processing 10 files sequentially.

In the **Threads number** field, enter a number.

> [!NOTE]
> **Note**
> 
> You can limit the number of threads only if the 'Split message run' feature is enabled in the Connectivity Studio parameters.
  5. If you run a message in batch, you can rerun the message automatically if an error occurred during a message run.

You can apply one of these rerun options:

In the **Automatic retry** field, select an option.

> [!NOTE]
> **Note**
> 
> You can only rerun import messages that import data from a:
> 
> - File
> - Service Bus queue
> - Database
> - Staging journal
> 
> For imports, the rerun is only done if one of these errors occurred:
> 
> - TransientSqlError: The database connection is broken.
> - Deadlock: The import process is locked due to other processes.
> - Update conflict: The data to be updated is already changed.
    - **No**: The message is not rerun automatically.
    - **Rerun**: (Import messages only!) The message is rerun for the full set of provided data. For example, a data file is processed again.
    - **Rerun from history**: (Import messages only!) The records with errors, as stored in the message history, are rerun.
    - **Retry internal**: (Export messages only!) During batch processing of data export messages, TransientSqlConnectionError errors are detected when these occur. Automatically, a rerun attempt is done, without stopping the entire batch job.
  6. Define the maximum number of attempts to rerun the message automatically. This maximum number applies to both import and export messages

In the **Max. automatic retry attempts for import** field, enter a number.

> [!NOTE]
> **Note**
> 
> The number of rerun attempts has an impact on the performance. You are advised to limit the number of rerun attempts. The default and maximum number of attempts is ´5´. However, in most cases, a maximum of ´3´ rerun attempts is sufficient. A number higher than 5 is not considered.
13. Sub-task: Define custom settings.
  1. Expand the **Custom** section.
  2. If you run D365 F&SCM in the cloud, the message type must always be Standard.

If you run D365 F&SCM on premise, to improve performance, you can choose for SQL to export data from D365 F&SCM to external database. In this case, the message gets the data from the D365 F&SCM database and directly enters it into the external database. In this case, the required setup for the message is:

The source connector type is D365 F&SCM and document is of an internal document type.

The target connector type is **Database** and the document type is **ODBC**.

> [!NOTE]
> **Note**
> 
> The data is not exported via ODBC. The connector and document are used only for the setup. In this case, the handler must be '**BisMessageRunDirectSQL**'.

In the **Message type** field, select an option.

> [!NOTE]
> **Note**
> 
> If you use a source connector of type **Direct SQL**, the message type must be SQL as well.
  3. For a message, several standard handler classes are available. You can use a customized handler class. To do so, extend a standard handler class.

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

> [!NOTE]
> **Note**
> 
> For a list and descriptions of the standard message handler classes, refer to the “[Standard message handler classes](/data-management/docs/set-up-message#standard-message-handler-classes)” section in this topic.
  4. You can use a custom action menu item to manually start a message. You can run a message to either export or import data./p>

To make this work:

As a result, for a selected record, you can manually run the message from the form to which you added the action menu item.

In the **Action menu item name** field, type a value.

> [!NOTE]
> **Note**
> 
> Example: on the **Sales orders** page, you can select a record and click the action menu item button. The message is processed, and the selected sales order is exported.
    - Create the custom menu item. The action menu item must be of type class and must be linked to the '**BisActionRunMessage**' class. To avoid best practice warnings, in the menu item setup, define the permissions for the roles who can use the action menu item. As the action menu item is not linked to a RunBase class, you cannot run it in batch.
    - Add the action menu item to the form from where you want to start the message. For example, the Sales orders form to export a sales order.
    - Enter the name of the action menu item to the desired message in the **Action menu item name** field. For example, a message to export a sales order.
14. Sub-task: Define message owner.
  1. Expand the **Owner** section.
  2. Define who is the owner of the message.

In the **Responsible** field, enter or select a value.
15. Sub-task: Define EDI document flow.
  1. Expand the **EDI** section.
  2. For EDI, a document flow type must be assigned to each message. In EDI, you run the Process inbound EDI documents batch job for a specific document flow type, and optionally for a specific message. Each time the batch job is run, all document flows of the defined document flow type are processed. So, all messages, as defined for these document flows, are run. Each message that is run, picks up the relevant received EDI message files (if any) from the location as defined for the message connector and processes the data. For more information o documents flows, refer to the EDI documentation.

In the **Document flow** field, select an option.

> [!NOTE]
> **Note**
> 
> This field only applies to messages that are used for EDI.
16. Sub-task: Define splitting settings.
  1. Expand the **Split target per root record** section.
  2. For data export, it can be that a limited number of root records per file is allowed. You can define the maximum allowed number of records per file. If more records are included in one message run, these records are split over several files, based on the split quantity. For example, the split quantity is 1000 records, and 4500 records are processed. the records are split over five files. Another example: you can use this to post a sales order one-by-one to a webservice. For data import, it can be required to limit the number of root records in one journal. For example, it can be required that a journal has a maximum of 1000 lines. If the import has 6000 records, these are split over six journals.

In the **Split quantity** field, enter a number.

> [!NOTE]
> **Note**
> 
> When you have defined a split quantity and the message is run, it:
> 
> - Opens the target document to process the records till the split quantity is reached.
> - Closes the target document.
> - Runs the next message (if defined) till it is finished.
> - Opens the target document to process the next records till the split quantity is reached. And so on.
  3. You can define the next message to be run when a run of the current message is finished. When the current message run is finished, the defined next message is automatically started. For example, the current message imports to the staging journal. You can start the message that exports from the staging journal and imports to D365 F&SCM when the current message is finished. This processes all approved and to-be-processed staging journals.

In the **Next message** field, enter or select a value.

> [!NOTE]
> **Note**
> 
> If a split quantity is defined, the next message is run before the next split quantity is processed.

### Standard message handler classes

For a message, these standard handler classes are available:

| Handler class | Description |
| --- | --- |
| BisMessageRunDirect | This handler class runs the message by reading and writing all the applicable data, taking into account the message, connector, and document settings. The other standard handler classes are an extension of this handler class. |
| BisMdmMessageRunDirectV2 | Use this handler class for Master data management messages. This is an improved version of the BisMdmMessageRunDirect handler class. |
| BisMdmMessageRunDirect | Use this handler class for Master data management messages. |
| BisMessageRunDirectSQL | Use this handler class if the message type is SQL. It gets the data from the D365 F&SCM database and directly enters it into the external database. If the record exists in the external database, it is updated. If the record does not exist in the external database, it is inserted. |
| BisMessageRunDirectInsert | You can use this handler class if the message type is SQL. It gets the data from the D365 F&SCM database and directly enters it into the external database. It only inserts the records in the external database. |
| BisMessageRunDirectEdi | Use this handler class for EDI messages to switch company based on the EDI history instead of the change company settings on the message header. |
| BisMessageRunDirect_deleteSkip | Use this handler class to skip the error if a to-be-deleted record does not exist. The message continues with the next record without an error message. |

## Related

- [Customize message handler class](/customize-message-handler-class.md)
- [Improve integration performance](/improve-integration-performance.md)
- [Create separate files](/create-separate-files.md)
- [Report data import success or failure to the source](/report-data-import-success-or-failure-to-the-source.md)
- [Direct data export from D365 F&SCM to cloud database](/direct-data-export-from-d365-fscm-to-cloud-database.md)