Skip to main content

Using the Amazon SNS Messaging API

InterSystems provides an API you can use to publish messages using the Amazon Simple Notification Service (SNS). Your code acts as a publisher by creating a client and then calling the client’s methods to send messages. InterSystems IRIS also provides methods to create and delete Amazon SNS topics.

The Amazon SNS API is based on the common messaging classes that are shared by other messaging platforms. This page describes platform-specific variations in the work flow which these common classes establish.

In addition to the API described here, InterSystems provides specialized classes that you can use to send messages to Amazon SNS as part of an interoperability production.

Connecting to Amazon SNS

To create a connection to Amazon SNS:

  1. Create a settings object. To do this create an instance of %External.Messaging.SNSSettingsOpens in a new tab and set its properties as follows:

    • credentialsFile, a string specifying the location of your Amazon Simple Storage Service (S3) credentials file.

    • accessKey, a string containing your Amazon S3 access key. If you have specified a credentialsFile, you do not need to set this property.

    • secretKey, a string containing your Amazon S3 secret key. If you have specified a credentialsFile, you do not need to set this property.

    • sessionToken, a string containing an Amazon S3 session token. If you have specified a credentialsFile which includes a session token, you do not need to set this property.

    • region, a string specifying an Amazon S3 region.

    For example:

     Set settings = ##class(%External.Messaging.SNSSettings).%New()
     Set settings.credentialsFile = "~/.aws/credentials/cred.ini"
     Set settings.region = "us-east-1"
  2. Create the messaging client object. To do this, call the CreateClient() method of the generic %External.Messaging.ClientOpens in a new tab class, passing the settings object as the first argument. For example:

     Set client = ##class(%External.Messaging.Client).CreateClient(settings, .tSC)
     // If tSC is an error, handle error scenario

    The method returns a status code by reference as the second argument. Your code should check the status before proceeding.

    Because the settings object is an instance of %External.Messaging.SNSSettingsOpens in a new tab, the returned object (client) is an instance of %External.Messaging.SNSClientOpens in a new tab.

Amazon SNS Publishers

InterSystems IRIS can act as an Amazon SNS publisher by calling API methods to create messages and then send them. If the application needs to create the topics where messages will be sent, see Working with Topics. The following flow uses the client object to interact with Amazon SNS as a publisher:

Create Message

To prepare a message to be sent, create a new instance of the %External.Messaging.SNSMessageOpens in a new tab object. Then, define properties for that message object. You must specify the Amazon Resource Name (ARN) for the topic where the message will be sent (the topicARN property) and a message body (the message property). You can also specify an optional subject for the message.

 Set topicARN = "arn:aws:sns:us-east-1:123456789012:quick-start-events"
 Set message = "MyMessage"
 Set subject = "EventNotification"

 Set msg = ##class(%External.Messaging.SNSMessage).%New()
 Set msg.topicARN = topicARN
 Set msg.message = message
 Set msg.subject = subject
Send Message

After creating a message, you can send it to the topic by executing the SendMessage() method for the Amazon SNS client object. For example:

 set tSC = client.SendMessage(msg)
 if $$$ISERR(tSC) {
       //handle error scenario

Working with Topics

InterSystems IRIS provides an API that can be used to create and delete Amazon SNS topics.

Create a Topic

To create a topic, invoke the CreateTopic() method of the client object. The method accepts the topic name as an argument, and returns an ARN for the topic by reference. For example:

 Set topicName = "quick-start-events"
 Set topicARN = ""
 Set tSC = client.CreateQueue(topicName, .topicARN)

As an alterative, you can create the topic with a method that is common to all messaging platforms: %External.Messaging.Client.CreateQueueOrTopic()Opens in a new tab. However, this generic method does not return the ARN for the new topic, which is required by the API methods for deleting a topic and for sending a message. To use the API to perform these tasks with a topic created using CreateQueueOrTopic(), you must obtain the ARN for the topic manually.

Delete a Topic

An application can delete an Amazon SNS topic by invoking the DeleteTopic() method of the client object, providing the ARN of the topic as an argument.

 Set tSC = client.DeleteTopic(topicARN)

As an alterative, you can delete the topic with a method that is common to all messaging platforms. See %External.Messaging.Client.DeleteQueueOrTopic()Opens in a new tab for details.

Close Client

An InterSystems IRIS application that is done communicating with Amazon SNS should close the client with the Close() method. For example:

 Do:client'="" client.Close()
FeedbackOpens in a new tab