commercetools connector - Consignment Updates

Technical flow

The first stage validates 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 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 drive, 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 own 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 a consignment status update message.

It is possible to override certain parts of the code and extend its functionality. For example, fetching more details from Fluent and either saving it in commercetools or using it to drive extra logic.

Consignment Status

Once the consignment is created at Fluent, it sends the webhook with some custom data along with other details like consignment status to update the consignment status at commercetools.
Below are the custom fields at commercetools :

• flConsignment - Fluent Consignment Group key
• flConsignmentRef - Fluent Consignment Ref
• flConsignmentStatus - Fluent Consignment Status

Delivery Create Mechanism

In commercetools delivery is based on fulfilment items. Each delivery can be created for an item and a Parcel will be created against item quantity.
Use fulfilment item list with fulfilment quantity to create Delivery and parcels in commercetools.

commercetools Delivery fields and Consignment fields Mapping:

commercetools Parcel fields and Article fields Mapping

Consignment Process Example

Each Consignment will be created against the fulfilment, i.e. if there is more than one fulfilment then there will be more than one consignment. As shown in the below snapshots in commercetools the ordered item has two fulfilment and two delivery(consignment in fluent) against each fulfilment.

Inside the delivery tab, order items have parcel details like provider name, measurements, tracing URL etc. as shown below snapshot.

On the Fluent side, the consignment will look like the below snapshot.

Fluent Consignment Query

1query GetConsignmentById($consignmentId: ID!) {
2  consignmentById(id: $consignmentId) {
3    id
4    status
5    trackingLabel
6    consignmentReference
7    retailer {
8      id
9      ref
10    }
11    carrier {
12      name
13      id
14      type
15    } 
16    consignmentArticles {
17      consignmentArticleEdges: edges {
18        consignmentArticleNode: node {
19          article {
20            id
21            type
22            status
23            quantity
24            attributes {
25              name
26              type
27              value
28            }
29            description
30            height
31            weight
32            length
33            width
34            fulfilments {
35              fulfilmentEdges: edges {
36                fulfilmentNode: node {
37                  id
38                  status
39                  deliveryType
40                  type   
41                  items {
42                    fulfilmentItemEdges: edges {
43                      fulfilmentItemNode: node {
44                        ref
45                        filledQuantity
46                        requestedQuantity
47                        rejectedQuantity
48                        orderItem {
49                          ref
50                          id
51                        }
52
53                      }
54                    }
55                  }
56                }
57              }
58            }
59          }
60        }
61      }
62    }
63  }
64}

Fluent Webhook Consignment payload

The below payload will be pushed to the internal queue.

1{
2  "id": "c321a113-9307-4269-9a91-a2f99cefe07b",
3  "name": "fc.connect.order.webhook.consignment-status-update",
4  "accountId": "CNCTDEV",
5  "retailerId": "1",
6  "rootEntityId": "127",
7  "rootEntityType": "ORDER",
8  "rootEntityRef": "CC_G_FROM_POSTMAN_929",
9  "entityId": "137",
10  "entityRef": "cf45b633-d91a-4eb2-84c9-36495dd3fec3",
11  "entityType": "CONSIGNMENT",
12  "entityStatus": "COMPLETE",
13  "type": "NORMAL",
14  "attributes": {}
15}