Tutorial

How to Create a Subscription

In this tutorial, we are going to show how to create a subscription in a project running on the commercetools platform. Currently, we support following queue services, and in this tutorial we are going to cover this topic for Amazon Web Services Simple Queue Service (SQS) and Microsoft Azure’s Service Bus (SB).

Goal

Imagine you want to create a subscription that sends a notification via email to your customer when an order is created.

Following diagram simplifies the approach. Creating a subscription with the message ‘Order Created’ — and the right queue information — creates a message queue in SQS or SB. A client can then poll a message from the queue and — according to its body — apply an action e.g. sending an email notification.

Subscription simple use

Prerequisites

  1. For this tutorial, you need valid credentials for accessing commercetools platform projects at the ↗ Admin Center EU (or ↗ Admin Center US ). If you don’t have access to one of the commercetools Admin Centers, please have a look at Getting Started with the commercetools platform.

  2. Additionally, as mentioned earlier, this tutorial covers two paths:

  • You can either use AWS SQS. In this case, you need to have an AWS account, and to create an SQS queue. Here is an additional link that helps you to start with the SQS: Getting Started with Amazon SQS.

  • Or you can use [ASB] (https://azure.microsoft.com/en-us/services/service-bus/). In this case, you need to have an Azure account, and to create a queue in the Service Bus. Following link helps you to start with Azure Service Bus: Create a queue using the Azure portal.

Create a Subscription

Before we create a subscription, we need to gather some data from the queue service, we are using.

The next two subsections describe how to use use SQS and SB respectively. So if you are using AWS SQS go further with the next subsection, otherwise jump to the Azure Service Bus subsection.

Access and Queue

AWS

First of all, you need an access key ID and a secret access key. Follow this tutorial to find out how to create your own security credentials.

Then, you need a queue in SQS. This tutorial leads you through the creation of a queue and getting the url and the region of the queue.

Azure

First, you need to create a queue in the SB. Just be sure when you create the queue that the checkbox “Enable sessions” is unchecked, since this option is not supported by CTP.

The second step is to get the connection string needed to create an ASB subscription. This link helps you to accomplish this task.

Messages

As mentioned earlier, messages is an array of message subscriptions which require a resource type ID. Here is a list of the currently supported resourceTypeId.

Following code snippets show examples of passing order as resourceTypeId in different languages.

Code Snippets for an AWS Subscription
#!/bin/sh
curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.sphere.io/{project-key}/subscriptions -d @- << EOF
{
	"destination": {
		"type": "SQS",
		"queueUrl": "<url-to-my-queue>",
		"accessKey": "<my-access-key>",
		"accessSecret": "<my-access-secret>",
		"region": "<my-region>"
	},
	"messages": [
		{
		    "resourceTypeId": "order"
		}
	]
}
EOF
{
  "destination": {
    "type": "SQS",
    "queueUrl": "<url-to-my-queue>",
    "accessKey": "<my-access-key>",
    "accessSecret": "<my-access-secret>",
    "region": "<my-region>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}
 final AwsCredentials awsCredentials = AwsCredentials.of("<my-access-key>", "<my-access-secret>");
 final SqsDestination destination = SqsDestination.of(awsCredentials, "<my-region>", URI.create("<url-to-my-queue>"));
 final List<MessageSubscription> messages = Arrays.asList(MessageSubscription.of(Order.resourceTypeId()));
 final SubscriptionDraft subscriptionDraft = SubscriptionDraftBuilder.of(destination).messages(messages).build();

 return client.execute(SubscriptionCreateCommand.of(subscriptionDraft));
<?php
    $destination = SQSDestination::ofQueueURLAccessKeyAndSecret('<url-to-my-queue>', '<my-access-key>', '<my-access-secret>')->setRegion('<my-region>');
 $messages = MessageSubscriptionCollection::of()->add(MessageSubscription::of()->setResourceTypeId('order'));
 $subscriptionDraft = SubscriptionDraft::ofDestinationAndMessages($destination, $messages);
 $request = SubscriptionCreateRequest::ofDraft($subscriptionDraft);
 $response = $client->execute($request);
 $subscription = $request->mapResponse($response); 
Code Snippets for an SB Subscription
<?php
    $destination = AzureServiceBusDestination::ofQueueURLAccessKeyAndSecret('Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>');
 $messages = MessageSubscriptionCollection::of()->add(MessageSubscription::of()->setResourceTypeId('order'));
 $subscriptionDraft = SubscriptionDraft::ofDestinationAndMessages($destination, $messages);
 $request = SubscriptionCreateRequest::ofDraft($subscriptionDraft);
 $response = $client->execute($request);
 $subscription = $request->mapResponse($response); 

If the creation of the subscription was successful you will get a response similar to this:

An AWS subscription
{
    "changes": [],
    "createdAt": "<timestamp>",
    "destination": {
        "accessKey": "<my-access-key>",
        "accessSecret": "<my-access-secret>",
        "queueUrl": "<my-queue-url>",
        "region": "<my-region>",
        "type": "SQS"
    },
    "id": "<subscription-id>",
    "lastMessageSequenceNumber": 0,
    "lastModifiedAt": "<timestamp>",
    "messages": [
        {
            "resourceTypeId": "order",
            "types": []
        }
    ],
    "version": 1
}
An SB subscription
{
    "changes": [],
    "createdAt": "<timestamp>",
    "destination": {
        "connectionString": "<my-connectionString>",
        "type": "AzureServiceBus"
    },
    "id": "<subscription-id>",
    "lastMessageSequenceNumber": 0,
    "lastModifiedAt": "<timestamp>",
    "messages": [
        {
            "resourceTypeId": "order",
            "types": []
        }
    ],
    "version": 1
}

Example of Receiving a Message using PHP and SQS

Now, let’s receive a message from the queue and use the content of its body to send the notification to the user. In order to receive a message, we have to poll it from the queue. For the purpose of this tutorial, we will only print the message we receive in the browser. In the following example code we use PHP. But you are free to use any language you prefer.

Create a PHP file with the snippet below. For the client we used the factory method, see the SQS documentation for more details.

$client = SqsClient::factory(array(
    'profile' => '<my-profile>',
    'region'  => '<my-region>'
));

$result = $client->receiveMessage(array(
    'QueueUrl' => <my-queue-url>,
));

foreach ($result->getPath('Messages/*/Body') as $messageBody) {
    // Do something with the message
    echo $messageBody;
}

When you run this code, and if you have a message in your queue, you will see its body in the browser.

Further Learning

From here, you can discover other subscription options the commercetools platform offer, e.g. update and delete subscriptions, as well as other predefined messages.