Skip to main content

Inbound Messages

Inbound messages are those sent to Business Central from an external system, typically triggered by the external system.

Inbound Integration Handlers​

Inbound integration handlers are created for every expected inbound message from an external system. Each handler defines:

  • Message Type and Source: EDI Partner, etc.
  • Data Import Method: See below for details.
  • Main Table: The message is based on this.
  • Partner Reference: e.g., External Document No.
  • Processing Time: Choose immediate (synchronous) or background (asynchronous) processing.

Import Methods​

The Import Method specifies how to process the payload in the integration message. The app supports:

  • Data Exchange
  • XML Port
  • Codeunit

Data Exchange​

This is the most common method, allowing you to map integration messages using configuration in the form of data exchange definitions. Supported formats include XML, JSON, and variable text files.

note

Fixed text is not supported by default.

Data Exchange Definition Setup​

Below are recommended settings for data exchange definitions for importing messages.

File TypeTypeData Handling CodeunitReading / Writing CodeunitUser Feedback CodeunitExt. Data Handling CodeunitFile Encoding  Column Separator
XMLGeneric Import70254543120370254544
JsonGeneric Import702545437025457870254544
CSVGeneric Import702545431220702545441240UTF-8/UTF-16Comma
Integration Hub Import type

Select Integration Hub Import as the Type and the codeunit fields above will be populated automatically based on the File Type you choose. You no longer need to enter these values manually. Selecting this type does not affect any downstream processing — it is only used to apply these defaults.

Time Zone Handling​

Integration Hub supports time zone conversion for date and datetime fields when importing messages. There are two levels of configuration:

  • Default Time Zone – Set on the Integration Hub Setup to specify the default time zone for your API. This applies to all date/datetime columns unless overridden at the column level.
  • Time Zone – Set on an individual Data Exchange Column Definition to override the default for a specific column. This is useful when different fields in the same message carry different time zones.

When a date or datetime value arrives in ISO 8601 format with a time zone offset (e.g., 2024-01-15T10:00:00+13:00), the app converts it correctly using these settings.

Supported Field Types​

The Data Exchange import supports the following additional field types:

  • BLOB fields – You can map text values from the incoming message directly to BLOB fields in Business Central.
  • Null values – When a JSON payload contains null for a decimal or date/datetime field, the app imports this as the default value for that field (zero for decimals, empty for dates). Previously, null values would cause an import error.

JSON Root Node Wrapping​

The Data Exchange import converts JSON payloads to XML internally before processing. This conversion relies on a built-in JSON-to-XML converter that requires a single top-level root object to produce a correct result. When the payload lacks one — for example, a bare array ([...]) or a document with multiple root elements — the converter may produce an incorrect XML structure or fail entirely, causing the import to fail.

To handle this, enable the Append Root Node field on the Data Exchange Definition card. This wraps the incoming JSON in a {"root": ...} envelope before XML conversion takes place, ensuring the converter always receives a well-formed single-root document. The field is only visible when File Type is set to JSON.

Path Updates​

Wrapping the payload adds an extra /root level to the resulting XML structure. All Data Line Tag values on line definitions and Path values on column definitions must account for this additional level.

When you toggle Append Root Node on or off, the system prompts you to update all paths automatically:

ActionBeforeAfter
Enabling/items/root/items
Enabling/items/id/root/items/id
Disabling/root/items/items
Disabling/root/items/id/items/id

Paths that already have the correct prefix (or already lack it) are left unchanged. You may decline the prompt and adjust paths manually if preferred.

Error Guidance​

If Append Root Node is disabled and the JSON cannot be converted due to a missing single root node, the resulting error message will direct you to enable Append Root Node on the Data Exchange Definition and update all mapping paths to include the /root prefix.

Data Exchange Definitions and Excellent Importer​

Minimum Version

The Excellent Importer integration features described below require Excellent Importer version 27.0.0.0 or later.

If you have our Excellent Importer app, connect the data exchange definition to an Excellent Importer Import Definition. Excellent Importer processes both Excel files and variable/fixed text files. Consider using Excellent Importer because:

  • You want to import fixed text files (which are unsupported by Data Exchange).
  • You prefer importing Excel files directly rather than converting them to text.
  • You want to leverage Excellent Importer's mapping and transformation features.
  • You need to skip specific records in the text file.
  • Your text file contains multiple record types (e.g. header and line), and you require values from both during processing.
  • You desire additional Excellent Importer features (e.g. Importing and Posting Journals).

Example: Using Excellent Importer with Integration Hub​

Inbound Integration Handler​

Select Data Exchange for the Import Methodon the Integration Handler.

Inbound Integration Handler

Data Exchange Definition​

Select Process using Excellent Importer for the Type. When you select this, you will notice that most fields will be hidden on the Data Exchange Definition page, and the Import Definition field will become available.

Data Exchange Definition

Excellent Importer - Import Definition​

This Import Definition is linked to a Sales Document import.

Import Definition

Excellent Importer - Mapping Template​

The Mapping Template is defined for a variable text file separated by commas.

Import Definition

Process to Excellent Importer (Staged Data)​

The Process to Excellent Importer (Staged Data) type allows Integration Hub to map an incoming structured payload (JSON, XML, etc.) into a generic staging table and then automatically trigger Excellent Importer to process it. This lets you reuse Excellent Importer's mapping, transformation, and posting logic without extending business tables or duplicating configuration.

Consider this option when:

  • Your payload is JSON or XML and requires complex concatenation or transformation logic already configured in Excellent Importer.
  • You want to avoid building custom staging tables or duplicating import logic.
  • Your integration maps naturally to an existing Excellent Importer import definition.
How It Works​
  1. Integration Hub receives the inbound payload and parses it using the Data Exchange column mapping.
  2. The parsed data is written into a generic internal staging table.
  3. Integration Hub automatically triggers Excellent Importer.
  4. Excellent Importer reads the staged data as if it were a file, applying its standard mapping, transformation, and posting logic.
  5. Staged data is cleaned up after processing (configurable in Excellent Importer).
Setup​
  1. Set the Type on the Data Exchange Definition to Process to Excellent Importer (Staged Data).
  2. Configure the Data Exchange Definition column mapping to target the staging table fields.
  3. Link an Import Definition in Excellent Importer that reads from the staging table.
note

Header and line records are supported. Deeply nested (3+ level) hierarchical payloads are not in scope for this feature.

XML Port​

Create an XML Port for messages with high volumes of records (thousands of rows). Though AL development is required, it is more efficient.

Codeunit​

This method uses a custom Codeunit to execute specific logic related to the received message, requiring custom development.

Testing Inbound Integration Handlers​

Select "Import and Process Message". This will:

  • Create an integration event entry and prompt you to select a file
  • Trigger the integration as if the file was received externally

Processing Integration Messages in the Background​

Configure inbound integration messages to be processed in the background, which is ideal for large payloads to avoid timeouts. When a message is set for background processing, it will create an entry in the Integration Job Queue Entry and then complete.

caution

Only message validation occurs in the background. A separate call is required to check the processing status.

Integration Job Queue Entry​

AAD Applications users aren't considered licensed and can't create scheduled tasks, impacting integrations needing background processing. To address this:

  • An entry is created in the Integration Job Queue Entry table, mirroring the Job Queue Entry.
  • A job queue entry configured to run Codeunit 70254552 - ProcessIntJQEntries_IH_TSL reads this queue table and creates a Job Queue Entry for background processing.

This setup ensures Job Queue Entry creation by licensed users only. Additional cues on the integration activities page show record statuses.

See Also​

tip