Amazon SNS Adapter

With the Amazon SNS adapter, a user can access the Amazon Simple Notification Services. This adapter connects to the Simple Notification Services (SNS) topics, using AWS keys. The adapter can fetch and send notifications from and to those AWS SNS topics, to which the user has subscribed.

This document provides an overview and the functional specifications of the Amazon SNS Adapter. The Amazon Simple Notification Service is a notification service provider that can deliver messages in mass, predominantly to mobile users. The Amazon SNS allows for creating topics. A topic is a logical communication-channel to launch mass delivery of a particular category of message. A topic supports high-throughput, push-based, and many-to-many messaging. The function of an SNS Adapter is to access the SNS topics the user has subscribed to for sending and fetching notifications to and from those topics. The SNS topics reside in various geographic regions as served by the Amazon Web Services (AWS). The AWS denotes every geographic region by a specific region code. The same code must be used—in the exact format—in the adapter properties for specifying any region. For more information on AWS SNS, refer https://aws.amazon.com/sns/.

The Amazon SNS adapter uses the PUT functionality to push notifications to a specified topic as a target in an output card. An SNS adapter cannot be used as a source in an input card. The notifications can be only in text format. The Amazon SNS adapter does not support the predefined-schema-import option.

An AWS Identity and Access Management (IAM) user can be created in AWS for accessing the SNS services. This user represents a person or application that will interact with AWS. It is not the same as the AWS account root user. For more information, refer: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html

Adapter properties and commands

This section provides an overview of the adapter properties for defining connections and actions and importing schemas in the web UI in LNK. The following table lists all the properties, their scope, whether they are required or not, and the adapter commands they map to for use in the compiled maps and map executions. “DI” scope means the property is dynamically enumerated - the adapter is invoked during action configuration to provide the set of allowed values for that property. A detailed description of the properties is provided after the table.

Table 1. SNS Adapter properties
Adapter property	Scope CO: Connection DI: Discovery IC: Input card OC: Output card G: GET function P: Put function	Required	Corresponding adapter command must be used directly in GET and PUT functions
accessKey= access_key	CO	Yes	-AK `access_key`
secretKey= secret_key	CO	Yes	-SK `secret_key`
region= region_name	CO	Yes	-R `region_name`
topicArn= topic_arn	DI/OC/P	Yes	-TARN `topic_arn`
create Topic= create_topic	OC/P	No	-CT
logging=info\|errors\|verbose\|off	OC/P	No	-T[E\|V]?[+]? `[file_name]`
append_log=true\|false	IC/OC/G/P	No	-T[E\|V]?[+]? `[file_name]`
log_file_name=file_name	OC/P	No	-T[E\|V]?[+]? `[file_name]`

accessKey= access_key

This property specifies the access key of AWS user for the connection. The access key is used to sign programmatic requests to AWS API calls through the adapter. The access key can be used with -ACCESSKEY or -AK command.

secretKey= secret_key

This property specifies the secret key of AWS user for the connection. Like the user name and password, both the access key ID and secret access key are mandatory to authenticate SNS topic PUT requests. The secret key can be passed to the adapter with -SECRETKEY or -SK command.

region= region_name

The adapter uses the region name to connect to an AWS region for the IAM user account. A region can be passed to the adapter using -REGION or -R command.

topicArn= topic_arn

Topic Amazon Resource Name (ARN) format is used to identify any topic in AWS. This property specifies the topic ARN where notifications are stored. During action configuration, the SNS Adapter provides options to select topic ARN among available topics in that region. Also, the topic_arn property can be passed to adapter input or output cards using the -TOPICARN or -TARN commands.

For creating SNS topic, refer the link: https://docs.aws.amazon.com/gettingstarted/latest/deploy/creating-an-sns-topic.html.

createTopic= create_topic

If this property is specified, the SNS adapter is indicated to create a topic with the name passed in the ‘topic_arn’ property, if it doesn’t already exist. This property is optional. When the create_topic property is not specified, adapter checks if the topic already exists; if not it throws error. Create topic option can be passed to adapter input or output cards using -CREATETOPIC or -CT commands.

logging=info|errors|verbose|off

This property specifies the level of logging to be used for the log (trace) file produced by the adapter. The default is off. The value info means log informational and error messages, the value error means log error messages only, and the value verbose means log debug and trace level messages along with the informational and error messages.

append_log=true|false

This property flags to indicate the action to be taken when the specified log file already exists. When set to true, the log messages are appended to the file. When set to false: the file is truncated, and the messages are written to the empty file. The default value is true.

log_file_name=file_name

This is the name of the log file, where the log messages are to be written. If not specified, the default log file name m4s3.trc is used, and the file is stored to the directory in which the executed compiled map resides.

Examples_{Examples of PUT map function (GET not
supported in SNS Adapter)}

In the following example, assume that the adapter is used in a PUT function defined as follows:

PUT("SNS", " -AK AKSOMEACCESSKEY -SK SkSomeSecretKey/dBLo -R US_WEST_2 -TARN arn:aws:sns:us-west-2:123456789012:gsg-signup-notifications", inputdata) In this case if the topic ‘gsg-signup-notifications’ doesn’t exist in specified region, adapter will throw error since -CREATETOPIC/-CT is not present.

Now, assume the PUT map function was defined as follows:

PUT("SNS", " -AK AKSOMEACCESSKEY -SK SkSomeSecretKey/dBLo -R US_WEST_2 -TARN arn:aws:sns:us-west-2:123456789012:gsg-signup-notifications -CT",inputdata)

In this case, the adapter creates the topic ARN, and then pushes notification to the newly created topic.