Integration patterns and practices

This topic is intended to help architects and developers make sound design decisions when they implement integration scenarios for Microsoft Dynamics 365 for Finance and Operations, Enterprise edition.

The topic describes integration patterns, integration scenarios, and integration solutions and best practices for Finance and Operations. However, it doesn't include technical details about how to use or set up every integration pattern. It also doesn't include sample integration code.

The following table lists the integration patterns that are available for Finance and Operations.

Pattern Documentation
OData OData
Batch data API Recurring integrations
Data management API
Custom service Custom services
Consume external web services Consuming external web services
Synchronous vs. asynchronous integration patterns
Processing can be either synchronous or asynchronous. Often, the type of processing that you must use determines the integration pattern that you choose.

A synchronous pattern is a blocking request and response pattern, where the caller is blocked until the callee has finished running and gives a response. An asynchronous pattern is a non-blocking pattern, where the caller submits the request and then continues without waiting for a response.

The following table lists the inbound integration patterns that are available.

Pattern Timing Batch
OData Synchronous No
Batch data API Asynchronous Yes
Before you compare synchronous and asynchronous patterns, you should be aware that all the REST and SOAP integration application programming interfaces (APIs) that Finance and Operations provides can be invoked either synchronously or asynchronously.

The following examples illustrate this point. You can't assume that the caller will be blocked when the Open Data Protocol (OData) is used for integration. The caller might not be blocked, depending on how a call is made.

Pattern Synchronous programming paradigm Asynchronous programming paradigm
OData DbResourceContextaveChanges DbResourceContextaveChangesAsync
Custom service httpRequestetResponse httpRequesteginGetResponse
SOAP UserSessionServiceetUserSessionInfo UserSessionServiceetUserSessionInfoAsync
Batch data API ImportFromPackage BeginInvoke
Both OData and custom services are synchronous integration patterns, because when these APIs are called, business logic is immediately run in Finance and Operations. Here are some examples:

If OData is used to insert product records, the records are immediately inserted as part of the OData call.
If a custom service is used to look up on-hand inventory, business logic is immediately run as part of the JSON/SOAP call, and an inventory sum number is immediately returned.
Batch data APIs are considered asynchronous integration patterns, because when these APIs are called, data is imported or exported in batch mode. For example, calls to the ImportFromPackage API can be synchronous. However, the API schedules a batch job to import only a specific data package. The scheduling job is quickly returned, and the work is done later in a batch job. Therefore, batch data APIs are categorized as asynchronous.

Batch data APIs are designed to handle large-volume data imports and exports. It's difficult to define what exactly qualifies as a large volume. The answer depends on the entity, and on the amount of business logic that is run during import or export. However, here is a rule of thumb: If the volume is more than a few hundred thousand records, you should use the batch data API for integrations.

In general, when you're trying to choose an integration pattern, we recommend that you consider the following questions:

Is there a business requirement that the integration should be in real time?
What is the requirement for the peak data volume?
What is the frequency?
Error handling
When you use a synchronous pattern, success or failure responses are returned to the caller. For example, when an OData call is used to insert sales orders, if a sales order line has a bad reference to a product that doesn't exist, the response that the caller receives contains an error message. The caller is responsible for handling any errors in the response.

When you use an asynchronous pattern, the caller receives an immediate response that indicates whether the scheduling call was successful. The caller is responsible for handling any errors in the response. After scheduling is done, the status of the data import or export isn't pushed to the caller. The caller must poll for the result of the corresponding import or export process, and must handle any errors accordingly.


Create and update product information
A manufacturer runs Finance and Operations, but defines and configures its product by using a third-party application that is hosted on-premises. This manufacturer wants to move its production information from the on-premises application to Finance and Operations. When a product is defined, or when it's changed in the on-premises application, the user should see the same change, in real time, in Finance and Operations.


Recommended solution
This scenario is best implemented by using the OData service endpoints to create and update product information in Finance and Operations.+

In Finance and Operations:

Determine all the entities that are required for the integration.
Make sure that the OData service endpoints are available for the same set of entities.
In the third-party application:

When product information is created or modified in the third-party application, an OData call is made to Finance and Operations to make the same change.
Read the status of customer orders
A company runs Finance and Operations but has a self-hosted customer portal where customers can check the status of their orders. Order status information is maintained in Finance and Operations.