Tutorial

How to create a subscription (AWS SQS)

In this tutorial, we are going to showcase how to create a subscription – in a project running on the commercetools platform – with a queue in AWS SQS. Currently, we support following queue services.

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 AWS SQS. 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, this tutorial uses the AWS Simple Queue Service. So you need to have an AWS account, and to create a Amazon SQS queue. Here is an additional link that helps you to start with the AWS SQS.

Create a Subscription

Our subscription draft requires following data from AWS SQS.

AWS: Access and Queue

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 AWS SQS. This tutorial leads you through the creation of a queue and getting the url and the region of the queue.

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.

#!/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);

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

{
    "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
}

Receiving a Message using PHP

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, check the different AWS SQS libraries for that.

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.