Adobe commerce - Fulfillment
Changed on:
16 Nov 2023
Overview
The Fulfillment module allows Adobe Commerce to receive Fulfilment updates from Fluent and track these details against each order line.
Key Features:
- Adds a new handler to the order update webhook (from the order module) to accept and process fulfilment updates.
- Currently only tracks the details at each order line. Does not drive any behavior in Adobe like status changes or updates to orders or shipments.
Detailed Technical Description
Technical Details
The diagram below represents how an update from Fluent is processed in Adobe.
Fulfillment Webhook
Configuration
The settings below demonstrate how the handler is mapped to a Fluent Webhook message name. It is possible through the Adobe’s dependency injection to add more or even override the default settings.
1<type name="FluentConnector\General\Api\WebHook\HandlerFactoryInterface">
2 <arguments>
3 <argument name="handlers" xsi:type="array">
4 <item name="FulfilmentStatusChanged" xsi:type="string">FluentConnector\Fulfilment\Handler\FulfilmentHandler</item>
5 </argument>
6 </arguments>
7</type>Language: xml
Name: Fulfilment Webhook Configuration
Description:
[Warning: empty required content area]Validation
There are a few different validations executed before the actual webhook processing begins. These validations are part of a validation chain configured at di.xml as follows:
1<virtualType name="fulfilmentValidatorChain" type="FluentConnector\General\Model\WebHook\MessageValidatorChain">
2 <arguments>
3 <argument name="validators" xsi:type="array">
4 <item name="fulfilmentEnableValidator" xsi:type="object">fulfilmentEnableValidation</item>
5 <item name="fulfilmentEntityTypeValidator" xsi:type="object">fulfilmentEntityTypeValidation</item>
6 <item name="orderStatusValidator" xsi:type="object">FluentConnector\Fulfilment\Model\WebHook\Validator\OrderValidator</item>
7 </argument>
8 </arguments>
9</virtualType>Language: xml
Name: Fulfilment Validation di.xml
Description:
[Warning: empty required content area]Some of the validation includes:
- Fluent account details are aligned with the configuration in Adobe
- accountId
- retailerId
- Webhook entityType is FULFILMENT
- Order reference exists in Adobe
Processing
The webhook execution simply adds the message to a queue to be processed asynchronously.
Topic name:
`fluentcommerce.fulfilment.updater`Message content: * retailerId (retailer id) * entityId (Fluent Fulfilment Id) * entityRef (Adobe Fulfilment ID) * rootEntityRef (Adobe Order increment Id)
Fulfilment Processing
The extensions use Adobes standard approach to process items waiting in a queue. The diagram below illustrates the sequence of events for each queued item.
- Consume messages from the queue
- Fetch fulfilment entity by ID from Fluent
- Run initial validation to make sure this fulfilment is related to our orders and order items
- order exists and matches with the queued item
- order item exists in the platform
- Update order item fulfilment status,
- use Command patterns for data processing
- keep the fulfilment details on a new entity order item fulfilment linked to the standard order item
Custom entity Order Item Fulfilment
- Entity structure
COLUMN NAME | TYPE | ADDITIONAL INFO |
entity_id | INT | auto increment |
order_id | INT | |
order_item_id | INT | |
sku | STRING | |
name | STRING | |
status | STRING | Fulfilment latest status |
metadata | JSON |
- Data mapping
Fluent Fulfilment | Adobe order_item_fulfilment | Comments |
entity_id | auto increment value | |
order.ref | order_id | order id |
items.fulfilmentItemEdges[].fulfilmentItemNode.orderItem.ref | order_item_id | order item id |
items.fulfilmentItemEdges[].fulfilmentItemNode.orderItem.product.name | name | Product name |
fulfilmentById.status | status | The latest item fulfilment status, for Example: 'packing' |
metadata | Aggregated fulfilment statuses per quantities [ {'status' : 'packing', 'quantity' : 1, 'fulfilment_id' : 123}, {'status' : 'handling', 'quantity' : 1, 'fulfilment_id' : 122} ] |
Module Architecture
- FluentConnector/Order/Handler/FulfilmentStatusUpdateHandler.php
- Handler to publish fulfilment messages to the message queue
- FluentConnector/Order/Model/MessageQueue/Consumer/Data/FulfilmentUpdateMessage.php
- Data interface for Message queue message
- FluentConnector/Order/Model/MessageQueue/Consumer/FulfilmentUpdateConsumer.php
- Fulfilment update Consumer
- FluentConnector/Order/Model/Command/Order/Item/StatusUpdate.php
- Order item status update command
CLI Commands
Force order ID to be updated from Fluent Commerce
`1bin/magento fluent:order:updater [orderID]`Runs the consumer manually. Note that it normally starts automatically.
`1bin/magento queue:consumers:start fluentcommerce.order.updater`User Experience
Admin Interface -> Order Details View
The extension adds some information to the display of each order line in the order details view in the items ordered section
- Fulfilment Status: display the latest order item fulfilment status
- Qty: displays additional information to the regular Adobe fields
