1. To-Increase Dynamics 365 for Finance & Operations
  2. EDI studio
  3. Activities

Set up message
Application task

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.


Standard procedure

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: 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:

  • 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: 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:

  • 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.
  9.1 Expand the History section.
  9.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.
  9.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: 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.
  9.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 Business integration parameters, in the History report path field.
  Select Yes in the Create history report field.
  9.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: Usually, you only store history when you test a message.
  9.6 On import, you can log which D365 FO 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: Usually, you only log changes when you test a message.
10. Sub-task: Define company-change settings.
  10.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.
  10.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.
  10.3 If company identifications from the source document differ from the company IDs in D365 FO, you can apply a transformation. Select the transformation that defines which source company identification maps to which D365 FO company ID.
  In the Transformation field, enter or select a value.
11. Sub-task: Define source-status update settings.
  11.1 Expand the Update source status section.
  11.2

You can change the status of a source record in:

  • D365 FO if you export data from D365 FO 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.
  11.3 Enter the status that is assigned to a record if the message is successfully processed.
  In the Processed status field, type a value.
  11.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.
  12.1 You can use the D365 FO batch processing to improve the performance by running batch tasks in parallel.
  Expand the Performance section.
  12.2

You can define how batch tasks are run when a message is processed. If the type is:

  • 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.
  In the Type field, select an option.
 

Note: Parallel processing is only applied if the message is run in batch.
  12.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: This field is only applicable if the source document is an external file-based document.
  12.4

If you run an import 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:

  • No: The message is not rerun automatically.
  • Rerun: The message is rerun for the full set of provided data. For example, a data file is processed again.
  • Rerun from history: The records with errors, as stored in the message history, are rerun.
  In the Automatic retry field, select an option.
 

Note:

You can only rerun import messages that import data from a:

  • File
  • Service Bus queue
  • Database
  • Staging journal

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.
  12.5 Define the maximum number of attempts to rerun the message automatically.
  In the Max. automatic retry attempts for import field, enter a number.
 

Note: The number of rerun attempts has an impact on the performance. You are advised to limit the number of rerun attempts. The default number of attempts is ´5´. However, in most cases, a maximum of ´3´ rerun attempts is sufficient.
13. Sub-task: Define custom settings.
  13.1 Expand the Custom section.
  13.2

If you run D365 FO in the cloud, the message type must always be Standard.

If you run D365 FO on premise, to improve performance, you can choose for SQL to export data from D365 FO to external database. In this case, the message gets the data from the D365 FO 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 FO and document is of an internal document type.
  • The target connector type is Database and the document type is ODBC. 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.
  13.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: For a list and description of the standard message handler classes, refer to the Notes section of this topic.
  13.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:

  • 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.

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: 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.
14. Sub-task: Define message owner.
  14.1 Expand the Owner section.
  14.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.
  15.1 Expand the EDI section.
  15.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: This field only applies to messages that are used for EDI.
16. Sub-task: Define splitting settings.
  16.1 Expand the Split target per root record section.
  16.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:

When you have defined a split quantity and the message is run, it:

  1. Opens the target document to process the records till the split quantity is reached.
  2. Closes the target document.
  3. Runs the next message (if defined) till it is finished.
  4. Opens the target document to process the next records till the split quantity is reached. And so on.
  16.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 FO 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: If a split quantity is defined, the next message is run before the next split quantity is processed.

Notes

For a message, these standard handler classes are available:

  • 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 FO 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 FO 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 his 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.

See also

Provide feedback