Simple Notification Service (SNS)

SNS is a push notification product that sends email and text messages based on its configuration. In conjunction with Skuid, this service can be used to send both custom messages—created by the user at runtime—and automated messages to specific endpoints, perhaps notifying interested parties of updates to particular records.

For more general information, see Amazon’s Getting Started with Amazon Simple Notification Service.

Configuration

First configure an authentication provider using your AWS security credentials. After doing so, configure a data source—choosing Amazon SNS as the data source type.

AWS Access Permissions

When using AWS APIs, it is best practice to utilize strict and well-defined IAM policies so users can only perform actions they have explicit access to.

Listed below are the permissions this data source type requires to properly function. Use this list to better define your IAM roles.

  • listTopics
  • listSubscriptionsByTopic
  • listSubscriptions
  • createTopic
  • deleteTopic
  • publish
  • subscribe
  • unsubscribe

Using the AWS SNS data source

The SNS data source type contains only two entities, Topic and Subscription. Of the two, only Topic may be directly edited within Skuid components. Instead, this data source type’s potential lies within the interplay of its data source actions and Skuid components attached to these entities—which can then provide context.

Some basics:

  • Endpoint: A phone or email address that can receive a message from SNS.
  • Topics: A “message hub,” typically used for a specific subject matter or specific service. Messages are published to topics, which are then sent to all subscribed endpoints.
  • Subscription: The connection between an endpoint and a topic. A subscription ensures that messages published to a topic make their way to a specified endpoint.
  • ARNs (Amazon Resource Numbers). These are the unique identifiers of an Amazon resource.

Topic

The Topic entity returns a list of topics. New topics can be created within Skuid components, but data source actions must be used to publish messages to topics.

Fields

  • Name (default): The user-friendly name assigned to a topic.
  • Region: The geographical region in which the SNS topic resource is hosted.
  • Topic ARN: The unique identifier of the topic, which functions like a topic record ID. Used for several data source actions.

Subscription

The Subscription entity returns a list of subscriptions connected to a specified topic. It is read-only within Skuid components, but subscriptions can be added and deleted through the use of data source actions.

Fields

  • Endpoint: The email or phone number subscribed to the topic of the subscription.

  • Owner: This field relates to the owner of the topic of the subscription.

  • Protocol: Displays which protocol the subscription uses to deliver messages to an endpoint.

    For a list of SNS protocols, see AWS documentation.

  • Region: The geographical region in which the SNS subscription resource is hosted.

  • Subscription ARN: The unique identifier for this individual subscription, which functions like a subscription record ID.

  • Topic ARN: The unique identifier for the topic to which the endpoint is subscribed.

  • Topic Name: The user-friendly name assigned to the topic of the subscription.

Conditions

  • Topic (Required): Setting this condition’s value to a topic’s ARN will limit the model’s data to that topic’s subscriptions. If this condition is not set, this model will be unable to load data.

Data source actions

The power of the SNS data source type comes from its data source actions. While the Subscription model entity is read-only, these actions facilitate SNS subscription and message publishing.

  • Publish to Topic: Publishes a message to a topic, which SNS disperses to all endpoints subscribed to that topic.

  • Send Text to Number:

  • Subscribe to Topic: Used to subscribe an endpoint to an existing topic. Most likely to be used as a row action on a table for the Topic model entity.

    • Protocol: Set which protocol the subscription will use to deliver messages to an endpoint.

      For a list of SNS protocols, see AWS documentation.

    • Endpoint (phone/email): The phone number or email that will be subscribed to the topic. Accepts static strings as well as merge syntax.

    • Topic ARN: The ARN for the topic being subscribed to. Accepts static strings as well as merge syntax.

  • Unsubscribe from Topic:

    • Subscription ARN: The ARN for the topic being unsubscribed from. Accepts static strings as well as merge syntax.

Most of these actions require a topic ARN and a message. While these values can be set manually within the App Composer, they can also be passed in using merge syntax. Because of this, you’ll most often use these data source actions within:

  • Table Row actions: When applied as row actions on table for the Topic entity, the ARN fields can be passed in as context.

  • Button Sets and UI-only models: By attaching a Field Editor to a UI-only model, you provide end-users with a form to enter the necessary information. By setting the Button Set component to that same model, buttons can be created for the actions that then receive the appropriate data.

    For example, end-users can enter a message and a topic ARN in the Field Editor. They can then publish this message through a button in the Button Set.

Troubleshooting

  • When trying to select a model entity, I receive “An internal server error occurred”

    The IAM user associated with your AWS access credentials within your Skuid authentication provider probably does not have the appropriate permissions for the service you are accessing. Return to the AWS console and ensure your IAM policy settings are correct.

    If your policy settings are correct, recreate your authentication provider with a new access key.