Introduction

The Anypoint Amazon SNS Connector provides connectivity to the Amazon Simple Notification Service (Amazon SNS) API, enabling you to build distributed web-enabled applications. Mule applications can use the Amazon SNS Connector to easily push real-time notification messages to interested subscribers over multiple delivery protocols.

Prerequisites

To be able to use the Amazon SNS Connector, you must have the following:

  • Access to Amazon Web Services - SNS.

  • To access AWS with the connector, you will need the credentials in the form of IAM.

  • Anypoint Studio - Enterprise Edition.

Requirements

For Hardware and software requirements, please visit Mulesoft.com.

Compatibility

Amazon SNS connector is compatible with:

Application/Service Version

Mule Runtime

3.5.0 or later

AWS SDK for Java

1.10.1

Java

1.7.0_x

Anypoint Studio

5.2 or higher

Installing and Configuring

The following sections describe how to install and configure Amazon SNS connector.

Installing

You can install a connector in Anypoint Studio using the instructions in Installing Connectors.

Configuring

To use the Amazon SNS connector in your Mule application, you must configureĀ a global Amazon SNS element that can be used by all the Amazon SNS connectors in the application.

Read more about Global Elements.

Setting up the Global Configuration

[tab,title="Studio Visual Editor"]
....
. Click the **Global Elements** tab at the base of the canvas.
. On the **Global Mule Configuration Elements** screen, click **Create**.
. In the **Choose Global Type** wizard, expand **Connector Configuration** and select **Amazon SNS: Configuration** and click **Ok.**
+
[.center.text-center]
image:sns_config_global_wizard.png["Global Element Configuration Wizard"]
+
. Configure the parameters according to instructions below.
+
[.center.text-center]
image:sns_config_global.png["Global Element Configuration"]
+
[width="80%",cols="30a,70a",options="header"]
|===
|Parameter|Description
|*Name*|Enter a name for the configuration to reference it.
|*Access Key*|Alphanumeric text string that uniquely identifies the user who owns the account.
|*Secret Key*|Key that plays the role of a password.
|*Try AWS Credentials Provider Chain*|Checkbox that controls whether temporary credentials should be used.
|*Region Endpoint*|Set the topic region endpoint.
|*Topic Arn*|Topic ARN to test the connectivity.
|===
+
[NOTE]
In the image above, the placeholder values refer to a configuration file placed in the
`src` folder of your project. See link:/mule-user-guide/v/3.7/configuring-properties[Learn how to configure properties].

You can either enter your credentials into the global configuration properties, or reference a configuration file that contains these values. For simpler maintenance and better re-usability of your project, Mule recommends that you use a configuration file. Keeping these values in a separate file is useful if you need to deploy to different environments, such as production, development, and QA, where your access credentials differ. See
link:/mule-user-guide/v/3.7/deploying-to-multiple-environments[Deploying to Multiple Environments] for instructions on how to manage this.

. Keep the *Pooling Profile* and the *Reconnection tabs* with their default entries.
. Click *Test Connection* to confirm that the parameters of your global configuration are accurate, and that Mule is able to successfully connect to your instance of Amazon S3. Read more about this in  link:/mule-user-guide/v/3.7/testing-connections[Testing Connections].
. Click *OK* to save the global connector configurations.
....
[tab,title="XML Editor"]
....
First, ensure that you have included the Amazon SNS namespaces in your configuration file.

[source,xml,linenums]
----
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns:sns="http://www.mulesoft.org/schema/mule/sns" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
	xmlns:spring="http://www.springframework.org/schema/beans" version="EE-3.7.1"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/sns http://www.mulesoft.org/schema/mule/sns/current/mule-sns.xsd">

<!-- Put your flows and configuration elements here -->

</mule>
----

Follow these steps to configure an Amazon S3 connector in your application:
Create a global Amazon S3 configuration outside and above your flows, using the following global configuration code.

[source,xml,linenums]
----
<sns:config name="Amazon_SNS__Configuration" accessKey="${amazon.accesskey}" secretKey="${amazon.secretkey}" topicArn="${amazon.sns.topic.arn}" doc:name="Amazon SNS: Configuration"/>
----
....

Updating From an Older Version

Every time an updated version of a connector is released, Anypoint Studio displays a popup in the bottom right corner of your system with the following message: Updates Available.

To upgrade to the newer version of the Amazon SNS connector:

  1. Click the popup and check for the available updates.

  2. Select the Amazon SNS connector version 2.1.0 check box and click Next.

  3. Follow the instructions provided by the user interface.

  4. Restart Studio when prompted. After restarting, if you have several versions of the connector installed, Mule asks you for the version of the connector to use.

We have made the following updates in version 2.x of the connector:

  • For most of the operations the input and output attributes have been modified. For example, Add Permission operation refers to POJO object org.mule.modules.sns.model.AddPermission instead of com.amazonaws.services.sns.model.AddPermissionRequest.

Using This Connector

Amazon SNS connector is an operation-based connector, which means that when you add the connector to your flow, you need to configure a specific operation for the connector to perform. The connector currently supports the following list of operations:

  • Add Permission

  • Confirm Subscription

  • Create Platform Application

  • Create Platform Endpoint

  • Create Topic

  • Delete Endpoint

  • Delete Platform Application

  • Delete Topic

  • Get Endpoint Attributes

  • Get Platform Application Attributes

  • Get Subscription Attributes

  • Get Topic Attributes

  • List Endpoint By Platform Application

  • List Platform Application

  • List Subscriptions By Topic

  • List Subscriptions

  • List Topics

  • Publish

  • Remove Permission

  • Set Endpoint Attributes

  • Set Platform Application Attributes

  • Set Subscription Attributes

  • Set Topic Attributes

  • Subscribe

  • Unsubscribe

Use Cases and Demos

Listed below are the few common use cases for the connector:

Sending Amazon SNS Messages to Amazon SQS Queues

Amazon SNS works closely with Amazon Simple Queue Service (Amazon SQS).By using Amazon SNS and Amazon SQS together, messages can be delivered to applications that require immediate notification of an event, and also persisted in an Amazon SQS queue for other applications to process at a later time.

Sending Amazon SNS Messages to HTTP/HTTPS Endpoints

You can use Amazon SNS to send notification messages to one or more HTTP or HTTPS endpoints. When you subscribe an endpoint to a topic, you can publish a notification to the topic and Amazon SNS sends an HTTP POST request delivering the contents of the notification to the subscribed endpoint.

Tips

Test the Connection

Use the Test Connection feature to validate the connection to the AWS SNS topic.

  1. Open the Amazon SNS Global Element Configuration.

  2. Click the Test Connection button. If Topic Arn or the Region Endpoint are invalid, you will get an eeror message.

    Wrong Topic Region Endpoint

  3. To solve this issue, Select the right region from the Region Endpoint dropdown.

Adding to a Flow

  1. Create a new Mule Project in Anypoint Studio.

  2. Add a suitable Mule Inbound Endpoint, such as the HTTP listener or File endpoint, to begin the flow.

  3. Drag and drop the Amazon SNS Connector onto the canvas.

  4. Click on the connector component to open the Properties Editor.

    Flow Settings

  5. Configure the following parameters:

    Field Description

    Basic Settings

    Display Name

    Enter a unique label for the connector in your application.

    Connector Configuration

    Connect to a global element linked to this connector. Global elements encapsulate reusable data about the connection to the target resource or service. Select the global SNS connector element that you just created.

    Operation

    Select Create topic from the drop-down menu.

    General

    Topic Name

    Enter a unique name for the topic.

  6. Click the blank space on the canvas to save your configurations.

Example Use Case

Send messages to Amazon SQS Queue.

When you subscribe an Amazon SQS queue to an Amazon SNS topic, you can publish a message to the topic and Amazon SNS sends an Amazon SQS message to the subscribed queue.

Sending messages to SQS Queue

You can now subscribe an Amazon SQS queue to an Amazon SNS topic using the AWS Management Console for Amazon SQS, which simplifies the process. Follow the steps mentioned in Subscribe Queue to Amazon SNS Topic.

  1. Create a new Mule Project in Anypoint Studio.

  2. Add the below properties to mule-app.properties file to hold your Amazon SNS and SQS credentials and place it in the project’s src/main/app directory.

    1
    2
    3
    4
    5
    6
    7
    8
    
    amazon.accesskey=<Access Key>
    amazon.secretkey=<Secret Key>
    amazon.sns.topic.arn=<SNS Topic ARN>
    amazon.sns.topic.region=<SNS Topic Region>
    
    amazon.sqs.queue.name=<SQS Queue Name>
    amazon.sqs.queue.region=<SQS Queue Region>
    amazon.sqs.queue.url=<SQS Queue URL>
  3. Drag a HTTP endpoint onto the canvas and configure the following parameters:
    sns http config props

    Parameter

    Value

    Display Name

    HTTP

    Connector Configuration

    If no HTTP element has been created yet, click the plus sign to add a new HTTP Listener Configuration and click OK (leave the values to its defaults).

    Path

    /

  4. Drag the Amazon SNS Connector next to the HTTP endpoint component.

  5. Configure the SNS connector by adding a new Amazon SNS Global Element. Click the plus sign next to the Connector Configuration field.

    1. Configure the global element according to the table below:

      Parameter Description Value

      Name

      Enter a name for the configuration to reference it.

      <Configuration_Name>

      Access Key

      Alphanumeric text string that uniquely identifies the user who owns the account.

      ${amazon.accesskey}

      Secret Key

      Key that plays the role of a password.

      ${amazon.secretkey}

      Region Endpoint

      Set the topic region endpoint.

      ${amazon.sns.topic.region}

      Topic Arn

      Topic ARN to test the connectivity.

      ${amazon.sns.topic.arn}

    2. Your configuration should look like this:

      sns use case config

    3. The corresponding XML configuration should be as follows:

      <sns:config name="Amazon_SNS__Configuration" accessKey="${amazon.accesskey}" secretKey="${amazon.secretkey}" doc:name="Amazon SNS: Configuration" testTopicArn="${amazon.sns.topic.arn}" region="${amazon.sns.topic.region}"/>
  6. Click Test Connection to confirm that Mule can connect with the SNS instance. If the connection is successful, click OK to save the configurations. Otherwise, review or correct any incorrect parameters, then test again.

  7. Back in the properties editor of the Amazon SNS connector, configure the remaining parameters:

    Parameter Value

    Basic Settings

    Display Name

    Publish message to topic (or any other name you prefer).

    Connector Configuration

    Amazon_SNS__Configuration (the reference name to the global element you have created).

    Operation

    publish

    General

    Define attributes

    Select to define the Publish attributes

    Topic Arn

    ${amazon.sns.topic.arn} (or any other topic arn).

    Message

    Hello World!

    Subject

    Testing publish to queue.

    publish message connector props

  8. Check that your XML looks like this:

    <sns:publish config-ref="Amazon_SNS__Configuration" doc:name="Publish message to topic">
        <sns:publish topicArn="${amazon.sns.topic.arn}"  message="Hello world!" subject="Testing publish to queue"/>
    </sns:publish>
  9. Add a Logger scope after the Amazon SNS connector to print the data that is being processed by the Publish operation in the Mule Console. Configure the Logger according to the table below.

    Parameter Value

    Display Name

    Logger (or any other name you prefer)

    Message

    Message ID: #[payload]

    Level

    INFO

    sns logger

  10. Now let’s add another flow to receive the message published by SNS.

  11. Drag a Flow scope onto the palette.

  12. Drag the Amazon SQS Connector next to the HTTP endpoint component and configure it according to the steps below:

  13. Click the plus sign next to the Connector Configuration field to add a new Amazon SQS Global Element.

    1. Configure the global element according to the table below:

      Parameter Description Value

      Name

      Enter a name for the configuration to reference it.

      <Configuration_Name>

      Access Key

      Alphanumeric text string that uniquely identifies the user who owns the account.

      ${amazon.accesskey}

      Secret Key

      Key that plays the role of a password.

      ${amazon.secretkey}

      Queue Name

      Set the name of the queue.

      ${amazon.sqs.queue.name}

      Queue URL

      Set the queue URL

      ${amazon.sqs.queue.url}

      Region Endpoint

      Set the queue reqion

      ${amazon.sqs.queue.region}

    2. Your configuration should look like this:

      sns-sqs-config

    3. The corresponding XML configuration should be as follows:

      <sqs:config name="Amazon_SQS__Configuration" accessKey="${amazon.accesskey}" secretKey="${amazon.secretkey}" doc:name="Amazon SQS: Configuration" defaultQueueName="${amazon.sqs.queue.name}" region="${amazon.sqs.queue.region}" url="${amazon.sqs.queue.url}"/>
  14. Click Test Connection to confirm that Mule can connect with the SQS instance. If the connection is successful, click OK to save the configurations. Otherwise, review or correct any incorrect parameters, then test again.

  15. Back in the properties editor of the Amazon SQS connector, configure the remaining parameters:

    Parameter Value

    Basic Settings

    Display Name

    Amazon SQS (Streaming) (or any other name you prefer).

    Connector Configuration

    Amazon_SQS__Configuration (the reference name to the global element you have created).

    Operation

    Receive messages

  16. Check that your XML looks as follows:

    <sqs:receive-messages config-ref="Amazon_SQS__Configuration" doc:name="Amazon SQS (Streaming)"/>
  17. Add a Logger scope after the Amazon SQS connector to print the data that is being passed by the Receive operation in the Mule Console. Configure the Logger according to the table below.

    Parameter Value

    Display Name

    Display Message (or any other name you prefer)

    Message

    Received Message : #[payload]

    Level

    INFO

Example Use Case Code

Paste this code into your XML Editor to quickly load the flow for this example use case into your Mule application.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?xml version="1.0" encoding="UTF-8"?>

<mule xmlns:tracking="http://www.mulesoft.org/schema/mule/ee/tracking" xmlns:sqs="http://www.mulesoft.org/schema/mule/sqs" xmlns:json="http://www.mulesoft.org/schema/mule/json" xmlns:sns="http://www.mulesoft.org/schema/mule/sns" xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation" xmlns:spring="http://www.springframework.org/schema/beans" version="EE-3.6.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/json http://www.mulesoft.org/schema/mule/json/current/mule-json.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd
http://www.mulesoft.org/schema/mule/sqs http://www.mulesoft.org/schema/mule/sqs/current/mule-sqs.xsd
http://www.mulesoft.org/schema/mule/sns http://www.mulesoft.org/schema/mule/sns/current/mule-sns.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/ee/tracking http://www.mulesoft.org/schema/mule/ee/tracking/current/mule-tracking-ee.xsd">
    <http:listener-config name="HTTP_Listener_Configuration" host="0.0.0.0" port="8081" doc:name="HTTP Listener Configuration"/>
    <sqs:config name="Amazon_SQS__Configuration" accessKey="${amazon.accesskey}" secretKey="${amazon.secretkey}" doc:name="Amazon SQS: Configuration" defaultQueueName="${amazon.sqs.queue.name}" region="${amazon.sqs.queue.region}" url="${amazon.sqs.queue.url}"/>
    <sns:config name="Amazon_SNS__Configuration" accessKey="${amazon.accesskey}" secretKey="${amazon.secretkey}" doc:name="Amazon SNS: Configuration" testTopicArn="${amazon.sns.topic.arn}" region="${amazon.sns.topic.region}"/>
    <flow name="publish_message_to_topic" >
        <http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
        <sns:publish config-ref="Amazon_SNS__Configuration" doc:name="Publish message to topic">
            <sns:publish topicArn="${amazon.sns.topic.arn}"  message="Hello world!" subject="Testing publish to queue"/>
            </sns:publish>
        <logger message="Message ID: #[payload]" level="INFO" doc:name="Logger"/>
    </flow>
    <flow name="recieve_message_from_queue">
        <sqs:receive-messages config-ref="Amazon_SQS__Configuration" doc:name="Amazon SQS (Streaming)"/>
        <logger message="Received Message : #[payload]" level="INFO"
                        doc:name="Display Message" />
        <logger message="Message with handle : #[header:inbound:sqs.message.receipt.handle]" level="INFO" doc:name="Display Message Handle"/>
    </flow>
</mule>

Run Time

  1. Save and run the project as a Mule Application.

  2. Open a web browser and check the response after entering the URL http://localhost:8081/. The logger will display the published message ID on the browser and the received message on the mule console.

Demo

You can download a fully functional example from this link.

See Also