Order Status Updates - commercetools Connector

Data Pipeline Execution

1. Ingestion (Webhook/Batch Job)

• Stage 1 (Ingestion & Queueing): The first stage is the validation of the signature and checks that 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.

2. Processing & Payload Extraction

• Stage 2 (Message Processing): 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 the commercetools-connector. Partners can utilize the same approach by adding their own handlers and enabling the processing of different messages that are specific to their end goals.
• All webhooks carry minimal information and require the commercetools-connector to fetch extra details from Fluent in order to complete processing the message received. The system extracts target lifecycle states out of the queue records to prepare them for status mapping evaluations.

3. Target State Mapping (commercetools Mutation/Fields)

• 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 single commercetools status.
• 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 the out-of-the-box (OOTB) implementation is mapped against the relevant Fluent order status.
• 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 the OOTB implementation is mapped against the relevant Fluent order status.
• The handler takes these three mapped values, wraps them inside an update action payload, and runs an update mutation to save the final states inside commercetools.

Data Storage & Schema Mapping

Status Mapping Configuration Profiles

• Order Status Configuration Key: `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 Configuration Key: `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 Configuration Key: `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}

Developer Extension Points

Storefront Status Update Mutation

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

Inbound Webhook Status Payload

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}