commercetools connector - Order Status Updates

The first stage is the validation of the signature and checks the content has the required parameters. If all goes well, the request is added to the internal message queue to be processed asynchronously; otherwise, the connector will return an error to Fluent to signal that it was unable to accept the request.

The second stage is the actual processing of the webhook message. The message name is key to driving how the message is going to be processed as these are mapped to internal handlers in commercetools-connector.

Partners can utilize the same approach by adding their handlers and enabling the processing of different messages that are specific to their end goals.

All webhooks carry minimal information and require commercetools-connector to fetch extra details from Fluent in order to complete processing the message received. The diagram below represents the flow executed for an order status update message.

It is possible to override certain parts of the code and extend its functionality. For example, it can fetch more details from Fluent and either save them in commercetools or use them to drive extra logic.

Technical Flow

In commercetools, there are 3 different order level status mappings:

• Order Status Mapping
• Payment Status Mapping
• Shipment Status Mapping

Order Status Mapping

The order status between Fluent and commercetools is kept in Fluent settings. The cardinality for order status mapping is Many-to-one; N number of Fluent order statuses can be mapped to the same commercetools status.

Fluent Mapping for Order Status

Add a property for the order status mapping in the fluent setting.

`order-status-mapping: "fc.connect.commercetools.order.order-status-mapping"`

1{
2  "fluent": {
3    "RECEIVED": "Open",
4    "PENDING_PAYMENT": "Open",
5    "ESCALATED": "Open",
6    "BOOKED": "Confirmed",
7    "PICK_PACK": "Confirmed",
8    "PICK_PACK_CC": "Confirmed",
9    "AWAITING_COURIER_COLLECTION": "Confirmed",
10    "AWAITING_CUSTOMER_COLLECTION": "Confirmed",
11    "COMPLETE": "Complete",
12    "CANCELLED": "Cancelled"
13  }
14}

Payment Status Mapping

The payment status between Fluent and commercetools is kept in Fluent settings. The cardinality for payment status mapping is Many-to-one, N number of Fluent order statuses can be mapped to the same commercetools payment status. In commercetools, payment status is at the order header level so Out-of-the-box(OOTB) implementation is mapped against relevant Fluent order status.

Fluent Mapping for Payment Status

Add a property for the payment mapping in the fluent setting.

`payment-status-mapping: "fc.connect.commerce-tools.order.payment-status-mapping"`

1{
2    "fluent": {
3        "RECEIVED": "pending",
4        "PENDING_PAYMENT": "pending",
5        "BOOKED": "paid"
6    }
7}

Shipping Status Mapping

The shipping status between Fluent and commercetools is kept in Fluent settings. The cardinality for shipping status mapping is Many-to-one, N number of Fluent order statuses can be mapped to the same commercetools shipping status. In commercetools, overall shipping status is at the order header level so OOTB implementation is mapped against relevant Fluent order status.

Fluent Mapping for Shipping Status

Add a property for the Shipping mapping in a fluent setting.

`shipping-status-mapping: "fc.connect.commerce-tools.order.shipping-status-mapping"`

1{
2    "fluent": {
3        "RECEIVED": "Pending",
4        "BOOKED": "Pending",
5        "PICK_PACK": "Pending",
6        "AWAITING_COURIER_COLLECTION": "Shipped",
7        "COMPLETE": "Shipped"
8    }
9}

Order Update Mutation

Mutation to update the order in commercetools 

`fc-commercetools-module/src/main/resources/ct-updateorderNumber.graphql`

1mutation Search($id: String!, $version: Long!, $actions: [OrderUpdateAction!]!) {
2  search: updateOrder(id: $id, version: $version, actions: $actions) {
3    id
4  }
5}

Out-of-the-box(OOTB) above mutations are provided, and partners can override it as per their requirement.

Fluent Webhook Order status payload

The below payload will be pushed to the internal queue.

1{
2    "id": "b34281d0-ada4-11e9-a1a7-5da7a83b9sd97cd",
3    "name": "fc.connect.order.webhook.order-status-update",
4    "accountId": "ACME",
5    "retailerId": "1",
6    "rootEntityId": "123",
7    "rootEntityRef": "O_123",
8    "rootEntityType": "ORDER",
9    "entityId": "123",
10    "entityRef": "O_123",
11    "entityType": "ORDER",
12    "entityStatus": "SHIPPED",
13    "type": "NORMAL",
14    "attributes": {}
15}