1. To-Increase Dynamics 365 for Finance & Operations
  2. Connectivity studio
  3. Concepts

Customize message handler class
Concept

In Connectivity studio, usually, you can design the integration setup by configuration. Sometimes, it can be required to use a customization. This topic explains the standard message handler classes in Connectivity studio and how to customize these classes. Only use customized classes if you really need specific functionality.

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, considering 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.

Customize message handler classes

You can use a customized message handler class. To do so, extend a standard message handler class.
For each customized message handler class, you can change these methods as desired:

Method

Description

onOpen

Starts the process.

onReadEntitySet

Returns a new set of records from the source.

onCheckMappingCondition

In the record mapping, you can define a condition per record which is validated here. In this method, you can add custom record checks.

onCheckMappingFieldCondition

In the field mapping, you can define a condition per field which is validated here. In this method, you can add custom field checks.

onMappingTransactionBegin

Starts the transaction on the target document.

onStartMappingTable

This is before the mapping starts for a table.

onFindRecord

Using the key fields, this method searches for existing records. You can customize this method to apply template records.

onInitEntity

Creates the record when it does not exist.

onWriteField

Writes the field to the target record.

onDeleteEntity

Based on the mapping setting for a record, this method deletes records.

onReplaceEntity

First deletes the record if it exists, and then inserts a new record.

onUpdateEntity

Updates and validates the entity.

onInsertEntity

Based on the mapping setting for a record, it will insert records.

onKeepEntity

When a record exists, this method returns the applicable BisEntity class. This method is related to the Find and Find or fail return actions of the message record.

onFinishMappingTable

When the mapping for a record is finished, you can do an action. For example, update the document management attachments information.

onMappingTransactionCommit

Commits the transaction on the target document. This can be very useful for posting actions as all the lines are inserted or updated and committed to the database.

onMappingTransactionAbort

Aborts the transaction when it fails.

onClose

Ends the process. This method closes the transaction, the history, documents, and connectors.

The sequence of the methods is almost the same as the sequence which these are executed. These methods take the data from the source and process it to the target. The central method is: processEntitySet.

Examples

  • Post sales order packing slip after import
    You can post a sales order packing slip automatically after it is imported into D365 FO. If this is specific for the message, you can extend the BisMessageRunDirect message handler class. If posting the packing slip fails, the sales order packing slip still exists in D365 FO.
    To have the sales order packing slip posted after import, change the onMappingTransactionCommit method:

  • Import sales order via ODBC and report back the sales order status to ODBC
     On a message header, 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. You can modify the runNextMessage method to only include the imported record as query range for the next message. So, the next message is only run for the just imported record.
    For example, if you import a sales order via ODBC, you can use the next message to report back via ODBC that the sales order is created. You can modify the runNextMessage method to only include the just imported sales order when the next message is run.

Related to Notes

Develop custom code

 		 

Set up message

 		 

See also

Provide feedback