Exchange data between systems

Warehouse management only mode requires that you set up integration between external systems and the Microsoft Dynamics 365 Supply Chain Management system. The following categories of interactions are required:

• Master data (such as product information)
• Document data (such as purchase orders and sales orders)
• Progress data (such as receiving, dispatch, and on-hand inventory information)

You can use many different integration methodologies for these three categories. This article describes the recommended integration process.

Master and reference data

To keep communication consistent, both systems need to sync and have access to several types of master and reference data. One example is the product master data. Import this type of data into Supply Chain Management by using the following messages that relate to product master data:

• WHSSourceSystemProductMessageEntity – Create products and released products, including product masters for variants.
• WHSSourceSystemProductVariantMessageEntity – Create variants for product masters where ProductSubtype = ProductMaster.
• WHSSourceSystemProductSpecificUnitOfMeasureConversionMessageEntity – Create product-specific unit-of-measure conversions.
• WHSSourceSystemProductBarcodeMessageEntity – Create the product bar code setup.
• WHSSourceSystemProductGlobalTradeItemNumberMessageEntity – Create the Global Trade Item Number (GTIN) for the products.
• WHSSourceSystemProductDocumentAttachmentMessageEntity – Attach product documents, product images, and so on.

Like shipment orders, the system validates these messages during message processing. The process automatically links the product information to a source system record through the Source system items entity. The external system can use business events to monitor how the status of messages changes during message processing.

You can mark only one source system record as the external system that maintains the product master data related to the unique reference for a released product or item number. Use the Source system items page to view and maintain this data.

Import the required master data into Supply Chain Management by using data entities. The following types of master and reference data are required to create the Release product/Item number value that's used in warehouse management processes:

• Item model groups – Assign each released product to an item model group in Supply Chain Management. Therefore, at least one group must be available. The group controls business processes for batch-tracked items. The following settings are recommended for every item model group that's used with Warehouse management only mode. These settings eliminate the need to set up any costing data for the products.

  • Inventory model – Set this field to Non-valuated.
  • Post physical inventory – Turn off this option. You can select this option only if you already set up at least one source system record.
  • Post financial inventory – Turn off this option. You can select this option only if you already set up at least one source system record.

• Item groups – Use these groups to organize business processes, especially when you use product filter codes. No account setup is required when you use Non-valuated inventory model groups.

• Storage dimension groups – Enable the use of storage inventory dimensions such as sites, warehouses, locations, and license plates. Be sure to enable the Use warehouse management processes parameter.

• Tracking dimension groups – Enable the use of tracking inventory dimensions such as owner, batch, and serial numbers. Note that the Owner dimension value must equal the company that a warehouse is associated with. Learn more in Unsupported processes.

• Reservation hierarchy – Defines which dimensions are reserved during the outbound shipment order reservation process. Dimensions that are put below the Location dimension are controlled by the warehouse management processes.

• Units – Each quantity that a warehouse process handles must be associated with a unit. When multiple units (such as each, box, and pallet) are used for an item, define the inventory unit as the smallest unit for the item.

• Unit sequence groups – Define the sequence of units that can be used in warehouse operations. Learn more about the required setup in Set up unit sequence groups.

View and maintain source system product messages

In Warehouse management only mode, you can view, update, and create product messages. This capability helps you quickly test integrations during the implementation process. When an externally created message is in a Failed message state, you can update field values and assign the updated message back into the message queue. The original message is versioned and non-editable. To view and maintain the messages, go to one of the following pages:

• Warehouse management > Source system products > Source system product messages
• Warehouse management > Source system products > Source system product variant messages
• Warehouse management > Source system products > Source system product barcode messages
• Warehouse management > Source system products > Source system product document attachment messages
• Warehouse management > Source system products > Source system product global trade item number messages
• Warehouse management > Source system products > Source system product specific unit of measure conversion messages

Use the Warehouse integration monitoring workspace to track the number of source system product messages that are Queued and Failed.

Source system inventory status mapping

When you use Warehouse management only mode with external shared warehouses, inventory statuses in your external source system might have different identifiers than the inventory statuses that you set up in Supply Chain Management. The source system inventory status mapping feature lets you create a mapping between your internal inventory status values and the values that your source systems use. The system then automatically translates inventory status values during inbound and outbound shipment order processing, including when inventory status is applied during order registration.

This mapping works in a similar way to source system items. While source system items map item numbers between systems, inventory status mapping maps inventory status identifiers between systems.

Prerequisites

To use source system inventory status mapping, you must be running Supply Chain Management version 10.0.49 or later.

Set up inventory status mapping

To set up the mapping between source system inventory statuses and Supply Chain Management inventory statuses, follow these steps:

1. Do one of the following:

   • Go to Warehouse management > Setup > Warehouse management integration > Source system inventory statuses.
   • Go to Warehouse management > Setup > Warehouse management integration > Source systems. Select the source system that you want to set up inventory status mapping for, and then select Source system inventory statuses on the Action Pane.

2. On the Action Pane, select New to create a new mapping record.

3. Set the following fields:

   • Source system – Select the source system that the mapping applies to.
   • Inventory status – Select the Supply Chain Management inventory status that this record maps to.
   • Source system inventory status – Enter the inventory status identifier that the external source system uses.

4. Repeat the previous steps for each inventory status that you need to map for each source system.

Import inventory status mapping by using data entities

You can import the inventory status mapping data by using the WHSSourceSystemInventoryStatusEntity data entity. Use the Data management framework to import records in bulk. The entity exposes the following fields:

How the mapping is applied

The system applies inventory status mapping in the following scenarios:

• Inbound shipment order updates – When an external warehouse sends an update that includes an inventory status (for example, as part of a receiving completed operation), the system uses the mapping to convert the source system inventory status to the corresponding Supply Chain Management inventory status. The mapped value is then used to register the purchase order or transfer order line transaction. Learn more in Inventory status in inbound shipment order update registration.
• Outbound shipment order updates – When an external warehouse ships inventory and generates a packing slip, the transaction data that's sent to the source system includes inventory status information. The system converts the Supply Chain Management inventory status to the corresponding source system value in the update message.
• Inbound and outbound shipment order requests – When shipment order request data includes inventory status dimensions, the system converts between source system and Supply Chain Management values, depending on the direction of the message.

If the system doesn't find a mapping for a given inventory status value, it processes the message without applying an inventory status conversion.

Inventory status in inbound shipment order update registration

In Supply Chain Management version 10.0.49 and later, when an external warehouse sends an inbound shipment order update that includes inventory status information, the system applies that status during registration processing in the source system legal entity. This process means that the registered purchase order or transfer order line transaction uses the inventory status from the external warehouse update, rather than the inventory status that was originally specified on the order line.

This behavior is important in scenarios where the external warehouse assigns a different inventory status during receiving. For example, if a purchase order line has an inventory status of Available, but the external warehouse determines during inspection that the goods should be marked as QualityInspection, the inbound shipment order update from the external warehouse includes the QualityInspection status. When the update is processed, the system registers the purchase order line with the QualityInspection status (after applying source system inventory status mapping, if configured).

The following example shows the end-to-end flow:

1. A purchase order line in the USMF legal entity has inventory status Available.
2. The order is released to the external warehouse (USSW) via an inbound shipment order request.
3. In USSW, warehouse workers receive the goods and assign inventory status QualityInspection during the receiving process.
4. Receiving is completed and an inbound shipment order update is sent back to USMF. The update includes inventory status QualityInspection (or its source system equivalent, if mapping is configured).
5. USMF processes the update. If source system inventory status mapping is configured, the system maps the source system status to the Supply Chain Management status. The purchase order line transaction is registered with the mapped inventory status.

Consigner and consignee information

To make it easier to set up your warehouse operation, create and use data for consigners and consignees and their related group definitions. For example, use this approach for a process that's related to setting up a quality order creation process for a specific consigner or consigner group.

Neither the Inbound shipment order policies (which are part of the Source systems setup) nor inbound shipment order message processing requires that the fields for the Consigner's account number value exist in the entity for the Consigners page (Warehouse management > Setup > Warehouse management integration > Consigners). The same "free text" concept exists for the outbound shipment order process that's related to the Consigner's account number value.

Country/region

To create a new legal entity for your warehouses and import outbound shipment orders, you must define country/region values in Supply Chain Management. Use these records in outbound shipment orders to create addresses. Depending on your address setup and the way that you use address fields in order messages, you might have to create additional data before you can import order messages (for example, to support state/province and county combinations).

Inbound and outbound shipment order messages

Use inbound and outbound shipment order messages to inform Supply Chain Management about which physical inventory to receive and ship. These messages include both header data and lines data.

• WHSInboundShipmentOrderMessageEntity – Create inbound shipment order header.
• WHSInboundShipmentOrderLineMessageEntity – Create inbound shipment order lines.
• WHSOutboundShipmentOrderMessageEntity – Create outbound shipment order header.
• WHSOutboundShipmentOrderLineMessageEntity – Create outbound shipment order lines.

Systems exchange messages by using lightweight inbound shipment order and outbound shipment order documents. These documents eliminate the need to use several other types of documents that Supply Chain Management typically uses, such as sales orders, purchase orders, and transfer orders. Therefore, they have several benefits. For example, they simplify integration with enterprise resource planning (ERP) and order management systems. They also make Supply Chain Management warehouse management functionality available to a wide range of external ERP and order management systems.

You can exchange inbound and outbound shipment order messages by using Dataverse. Alternatively, you can exchange these messages through Open Data Protocol (OData) by using shipment order message entities. You can also use the Data management import process. For example, you can use the Inbound shipment order messages composite entity (WHSInboundShipmentOrderMessageCompositeEntity) and Outbound shipment order messages composite entity (WHSOutboundShipmentOrderMessageCompositeEntity).

You can attach documents to inbound and outbound shipment order messages by using the Inbound shipment order message document attachment entity (WHSInboundShipmentOrderMessageDocumentAttachmentEntity) and Outbound shipment order message document attachment entity (WHSOutboundShipmentOrderMessageDocumentAttachmentEntity).

Supply Chain Management queues the incoming documents and then processes them by using the message processor. This approach ensures consistent data between the systems, both for master data (such as products) and order progress status. Therefore, Supply Chain Management inbound and outbound shipment orders are prevented from creating or updating nonvalid or unsupported order data. Process the messages as part of a periodic batch job that the message processor triggers by using the Shipment orders message queue.

The following illustration shows how the message processor fits into an integrated system.

Progress data and business events

External systems can send many different business process requests to the warehouse management system. For example, each external system can continuously check for the progress of a sales order. To support this process, you can set up Supply Chain Management to deliver business events as required. Business events keep external systems informed about the progress and actions that are occurring in Supply Chain Management. When you set up this process, the external systems don't have to continue to check for information that might not have changed since the last request. Instead, they can react only when they're informed.

Warehouse integrations support several out-of-the-box business events. The following table lists some of them.

Some business events don't include all journal details directly. In these cases, the event contains only the journal ID. You can use this ID to retrieve the full information through related data entities listed in the following table.

At a minimum, use the following business events for integration with an external ERP system:

• InventCountingJournalPostedBusinessEvent – Announces that an on-hand inventory adjustment occurred and indicates where detailed information about the update can be found.
• WHSSourceSystemInventoryOnhandReportBusinessEvent – Announces that an on-hand inventory report was generated and indicates where detailed information about the update can be found.
• WHSShipmentPackingSlipJournalModifiedBusinessEvent – Announces that an outbound shipment confirmation process occurred and indicates where the detailed dispatch advice data can be found. This data can be used for a sales invoicing process, for example.
• WHSShipmentReceivingJournalModifiedBusinessEvent – Announces that an inbound receiving completion process occurred and indicates where the detailed receiving advice data can be found. This data can be used for a purchase order invoicing process, for example.

On-hand adjustments

When you integrate an ERP system and a warehouse management system, keep on-hand inventory data aligned. Several processes can help maintain this alignment as part of the Warehouse management only mode implementation approach. For more information about how the inventory on-hand update process works, see On-hand inventory updates between systems.

Warehouse management only mode with external shared warehouses

You can set up an integration between Supply Chain Management and an external warehouse management system. To enable this integration, use external warehouse shipment order requests and updates for communication between the systems. Learn more in Warehouse management only mode with external shared warehouses.

Inbound and outbound shipment order requests

Use external warehouse inbound and outbound shipment order requests to import orders from Supply Chain Management into your warehouse management system. When you release an order to the warehouse, the system creates a business event with a request ID. Use this ID to retrieve full details through related data entities.

Inbound and outbound shipment order updates

Use external warehouse inbound and outbound shipment order updates to send shipment updates from your warehouse management system to Supply Chain Management. The message processor handles these updates in the same way as inbound and outbound shipment order messages.

• WHSEWInboundShipmentOrderUpdateEntity
• WHSEWInboundShipmentOrderLineUpdateEntity
• WHSEWInboundShipmentOrderLineInventDimUpdateEntity
• WHSEWOutboundShipmentOrderUpdateEntity
• WHSEWOutboundShipmentOrderLineUpdateEntity
• WHSEWOutboundShipmentOrderLineInventDimUpdateEntity

Outbound work-started updates

In Supply Chain Management version 10.0.50 and later, the external shared warehouse sends a work-started update to the order-owning legal entity when release to warehouse creates picking work. The update uses WHSEWOutboundShipmentOrderUpdateEntity and WHSEWOutboundShipmentOrderLineUpdateEntity. The WorkCreatedQty field on each line contains the cumulative quantity (in the item's inventory unit) for which work was created.

When the order-owning legal entity processes the update, it records the work-created quantities on the matching shipment load lines and changes the update status to Accepted. The update doesn't ship the shipment or change its processing ownership. If work is canceled and the order is released again, a new work-started update replaces the stored quantity instead of adding to it.

The source system determines how the picking-started notification is sent:

• If the source system is a legal entity in the same Supply Chain Management environment – The system sends the work-started update directly to the order-owning legal entity and doesn't raise WHSOutboundNotificationCreatedBusinessEvent.
• If the source system is an external system – The system raises WHSOutboundNotificationCreatedBusinessEvent with the notification status PickingStarted. Use WHSOutboundNotificationEntity, WHSOutboundShipmentNotificationEntity, and WHSOutboundShipmentLineNotificationEntity to read the notification details.

When a later shipment update is processed, the stored work-created quantity changes to the quantity that was actually picked. If processing ownership is claimed before a queued work-started update is processed, the message processor changes the update's processing status to Canceled. The canceled update doesn't modify the shipment. If ownership is claimed after the work-started update was processed, the system clears the stored work-created quantity. Claiming ownership doesn't cancel work in the external warehouse.

Unannounced sales returns from another warehouse management system

If your warehouse management system receives an unannounced sales return, it must update the Supply Chain Management system accordingly. To achieve this goal, send an external warehouse inbound shipment order update message to the Supply Chain Management system. Ensure that you include all required details and entities so the return update can be processed correctly.

• WHSEWInboundShipmentOrderUpdateEntity
  • Set the value of the InboundShipmentOrderOriginLinkType field to 1, which represents the ExternalOrigin enum value of the WHSInboundShipmentOrderOriginLinkType enum.
• WHSEWInboundShipmentOrderLineUpdateEntity
• WHSEWInboundShipmentOrderLineInventDimUpdateEntity
• WHSEWInboundShipmentOrderExternalOriginEntity
  • This entity provides additional required information.
  • The value of the InboundShipmentOrderExternalOriginId field must match the InboundShipmentOrderOriginId field on the WHSEWInboundShipmentOrderUpdateEntity entity. You can choose and maintain this ID.
  • Set the ExternalWarehouseManagementSystemId field to the external warehouse management system ID configured in your Supply Chain Management system.