Listening to messages from commercetools with Deno

When an entity is changed in commercetools, you can subscribe to this event by registering an external queue on Google Cloud Platform (GCP), AWS, Azure or Confluent cloud running Kafka. This is done through the subscription API. In production this is a rock-solid mechanism, allowing for guaranteed message delivery and processing.

The process of registering a subscription and using it is well described in the commercetools documentation tutorials on using subscriptions. However, in a proof of concept (POC) scenario, it can be a bit challenging to manage all of these subscriptions and make sure that all the client actions are doing what they are supposed to do. Sometimes it is more than enough to have a client running on your laptop that responds to changes in commercetools so you can perform some actions. In this article, I will describe one possible approach to enable rapid development around events that happen in commercetools.

While the explanation is somewhat hidden away in the documentation, commercetools also provides an API endpoint to pull event messages. This allows you to retrieve a list of messages that happened in the project. By default, the messages are not stored in commercetools, and need to be enabled thru the project API endpoint, by performing an update action on the project configuration:

When the messages configuration is enabled, you can retrieve a list of messages through the messages endpoint. Here is a small example using the Deno SDK:

This will elicit the following response:

This is logical if no updates have happened to an entity. However, let’s explore what happens when we create a customer:

And let’s retrieve the messages again:

This shows that we have a new message, with an ID, indicating that we have a new or changed resource of type customer. We can also see that there is a new customer created and we have the entire customer object.

So with this information, we can start pulling messages from commercetools at an interval. Every time a new message arrives, we can act upon it. Something like this:

Every time a resource has been changed, it will display the updated resource, until the program is stopped.

To make working with messages easier, I created a small helper that allows me to treat messages like incoming subscriptions. First, I created a simple registry where I can register to what resource I would like to listen. 

This allows me to only listen to changes on the customer, cart and order resources. 

If you look at the commercetools documentation, you can also see that there are many more details on the messages that I am also interested in. For instance, the customer entity can detect the following changes: Customer Created, Customer Deleted, Customer Address Changed, etc. Therefore it will raise an event in Deno when such a message is received. This allows me to register an event handler, that will only be called when a specific message type is coming in:

This will log a message when a change has been made to the customer entity, while the following handler will only log a message when the customer company name is set.

You can test this by using the following snippet, just make sure you have an .env file with the client details in the same folder as where you are running the script from:

listen.ts

Run this like: deno run -A listen.ts

When making a change to a resource, you should see the following on your terminal screen:

In an upcoming blog, I will create a module that will listen to an order and send an order confirmation by email using this same simple listener!

To learn more about how to use commercetools API extensions with Deno and run them on your laptop for demo or POC purposes, read my blog, A guide to enhancing commercetools API extensions with Deno.