5. commercetools Subscription

Build Outcome

By the end of this section we will have:

• Created a subscription that will emit Order Created Messages from commercetools

Steps

Subscription Overview

commercetools subscriptions are an event-based model that allow consumers to be notified of new or update conditions on a range of commercetools resources. In this tutorial we are interested in the order resource, specifically the created event.

From integration perspective, commercetools can deliver subscription messages directly onto a number of different messaging services, including, but not limited to:

• AWS SQS
• Google Cloud Pub/Sub
• Azure Event Grid

In this tutorial we’re going to use the Azure Service Bus that we created in the last section.

Creating a Subscription

Subscriptions are created using the commercetools API via a POST request to the subscriptions endpoint. The body payload supplied to this call requires the following high level detail:

• The message service type, e.g. Azure Service Bus, AWS SQS etc
• Configuration to allow commercetools to use the message service (this varies depending on the message service used)
• The messages that you are interested in, including detail related to:
  • The resource type, e.g. order, customer etc.
  • The message type, e.g. OrderCreated

The payload we’ll supply to the subscriptions endpoint to create a subscription that will use our service bus topic is:

{
  "destination": {
    "type": "AzureServiceBus",
    "connectionString": "Endpoint=sb://....."
  },
  "messages": [
    {
      "resourceTypeId": "order",
      "types": [
        "OrderCreated"
      ]
    }
  ],
  "key": "azure-queue"
}

The values you supply with your api call should be identical to those shown above, with the exception of the connectionString. You should provide the value of the connection string you generated when you created a shared access policy on your message bus instance.

The other values are self-explanatory, but 1 point of note is that you do not need to provide a value for types for each of the messages, (in this case we are filtering down to OrderCreated only). If you choose not to populate this value, you will receive all message types for the given resourceTypeId.

So to create a subscription:

1: Construct your payload and issue a HTTP POST request to the subscriptions endpoint (don’t forget to attach your API access-key too), an example using cURL is shown below:

curl -XPOST https://api.{region}.commercetools.com/{projectKey}/subscriptions 
-H "Content-Type: application/json" 
-H "Authorization: Bearer {access-token}" 
-d '{"destination":{"type":"AzureServiceBus","connectionString":"Endpoint=sb://<the rest of your connection string>"},"messages":[{"resourceTypeId":"order","types":["OrderCreated"]}],"key":"azure-queue"}'

A successful submission will result in 2 things:

1. A response payload
2. A test message will be placed onto the service bus

An example response payload is shown below:

{
  "id": "ce067694-8983-44bb-bb21-55f5f4e98d63",
  "version": 1,
  "versionModifiedAt": "2023-07-13T04:29:39.534Z",
  "createdAt": "2023-07-13T04:29:39.534Z",
  "lastModifiedAt": "2023-07-13T04:29:39.534Z",
  "lastModifiedBy": {
    "clientId": "abc123",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "abc123",
    "isPlatformClient": false
  },
  "destination": {
    "type": "AzureServiceBus",
    "connectionString": "Endpoint=sb://<your connection string>"
  },
  "messages": [
    {
      "resourceTypeId": "order",
      "types": [
        "OrderCreated"
      ]
    }
  ],
  "changes": [],
  "format": {
    "type": "Platform"
  },
  "status": "Healthy",
  "key": "azure-queue"
}

2: You can also navigate back to the service bus resource in the Azure Portal and observe that we had an incoming message placed onto the bus:

The message will remain on the service bus until:

• It expires, or:
• It is picked up by an endpoint (and the endpoint clears it down)
  • We will enable this in the next section

For now though, that is all we need to do to set up a subscription in commercetools.