Using Claris Connect with AWS Simple Notification Service (SNS)

Table of Contents: Claris Connect Series

• Claris Connect and Amazon Web Services (AWS) – Getting Started
• Using Claris Connect with AWS Simple Notification Service (SNS)
• How to Implement Custom Responses in a Claris Connect Flow
• Claris Connect and AWS S3
• Trapping and Handling Errors in Claris Connect Flows
• How to Integrate Claris Connect with Amazon SES
• How to Create Custom Connectors in Claris Connect

WRITTEN IN COLLABORATION

This blog post was written in collaboration with Matt Hintz. Our team often works together on research to drive innovation for our clients. Thank you, Matt, for all of your contributions to these insights.

In our previous blog post, we described Claris Connect as an orchestration tool to simplify integration between various APIs. We introduced the potential of leveraging this with AWS tools and the basics of setting up your Claris Connect and AWS accounts.

Now we’re ready to dive in and try out the first AWS service on our list: Amazon Simple Notification Service (SNS). We’ll discuss common use cases, how to set up SNS in Claris Connect, and benefits of this architecture.

SNS is a pub/sub messaging service to send and receive notifications from the cloud. This tool can send messages through email, SMS, mobile push notifications, etc. One common use case is an opt-in process in which a user is invited to a topic, accepts, and then receives notifications. At Soliant, we have used SNS to create various reporting subscriptions and notify key players of the status of a software deployment. You an also use SNS as an alternative to sending notifications via SMTP now that SMTP is being phased out by various vendors (e.g., Google and Microsoft. See our related post discussing this trend and the pivot to OAuth in response). To simplify these workflows and reduce the amount of code in our custom solutions, we can integrate SNS into our solution using Claris Connect

Claris Connect / AWS SNS – Supported Actions

Claris Connect has built-in connectors for various AWS services. It doesn’t, however, always support every feature that is available natively within AWS. In the case of SNS, the main functionality is supported in Claris Connect. The supported actions for SNS include:

• Create topic
• Delete topic
• Subscribe to a topic
• Subscribe using SMS
• Unsubscribe
• Publish message

More fine-tuned actions, such as GetSMSAttributes, ListSubscriptions, SetEndpointAttributes, etc., are not supported. However, the ability to manage topics, manage subscribers, and publish to a topic will cover most needs. In this post, we are going to focus on using the “Publish message” action to send a notification via a Claris FileMaker script to a topic already configured in AWS.

Setup an AWS Application-Specific Account

A best practice when setting up a new service in AWS is to create app-specific credentials with the least privilege required to use the specified service. Note that it was not quite possible to implement this least-privilege principle in the case of configuring our IAM account for Claris Connect. We found that we needed to set up the account to have “Full Access” in SNS. We initially tested with a custom Policy that included just the “Publish” action, which seems like the only functionality needed for the flow. However, establishing the app connection from within Claris Connect failed in that case.

Here we outline the steps for the SNS user account to use with Claris Connect:

1. Log into AWS and search for “IAM” (Identity Access Management).
2. In IAM, click on Users and Create New User.

We will name our user “sns_connect” for this blog post. This user does NOT need access to the AWS Management Console, so leave that selection unchecked.

3. At the Set Permissions step, select “attach policies directly,” search for “SNS,” and attach the “AmazonSNSFullAccess” Policy.

4. After creating this new user, Select the user in IAM and click on the security credentials tab.

Scroll down to the “Access Keys” section, click “Create access key” and select “Application running outside AWS” in step 1.

5. Upon completion, note the Access key and Secret access key values and store them in a secure place. We will use these to establish a connection between AWS SNS and Claris Connect.

IMPORTANT

This is your only chance to capture the Secret access key. Keep it in your password manager or another safe place. If you loose or forget it, you’ll need to deactivate the Access key and create a new set.

Setup SNS Topic and Subscribe

1. Back on the Console Home of your AWS account, choose an AWS Region in the upper right corner for setting up this SNS topic. We used “US-East-1 / N. Virginia” for this demo, but you can use any region that supports SNS. You may wish to choose the region that is closest to your end users’ location
2. Search for “SNS” in the search bar at the top and select SNS. Then, on the left sidebar, go to “Topics” → “Create Topic.”

Select “Standard” for the topic type and give the Topic a name – in this instance, we called it “Claris-Connect-To-SNS.”

You can scroll past all the additional “optional” sections and click the “Create topic” button at the bottom of the page.

3. After the topic has been created, note its ARN. We will need this in the setup of the Claris Connect flow. (ARN stands for Amazon Resource Number, click here for more information.)

4. Create a Subscription: At the bottom of the topic page, you can create subscriptions for the individuals or groups that you want to receive the notifications. Click “Create subscription.”

To fill out the details for the subscription, choose the Topic you just created, the Protocol, and the corresponding Endpoint of the notification channel you wish to use. For the sake of this blog post, we’re going to focus on Email only.

Choosing Your Notification Channels and Details

The screenshot below shows all of the available notification channels. While SMS seems like another obvious choice, be aware that the setup for this is quite a bit more involved. You must begin by establishing an “origin number” to identify as the sender’s phone number on the recipient’s device. AWS makes this part easy by allowing you to set up a phone number directly from your console (at a cost of $2 per month). However, with the recent evolution of regulations to address spam concerns, all origin numbers used in SMS campaigns must also undergo certain registration and review processes. This can take weeks to complete.

As the final step in creating your email subscription, you will receive an email with a link to confirm your subscription. Then you should see the following success message:

Create a Flow in Claris Connect

Now that your SNS topic is ready to go, it’s time to set up the Claris Connect Flow that will utilize it. As mentioned in our previous blog post, Connect offers a multitude of app connectors that could be used to trigger an SNS action. In this case, we are going to show how to do so from a Claris FileMaker script.

Using a Claris FileMaker Script

1. Log into your Claris Connect account, create a new project, and give it a unique name.
2. Create New Flow. We will call ours “Send Notification via SNS.”
3. Configure the Flow’s trigger. The search bar lets you filter by app. (You’ll notice that some apps in the display are greyed-out, indicating that they can’t be used as triggers for a Flow.) Search for “FileMaker” and select the appropriate connector for the server product that you use, e.g., “Claris FileMaker Server” or Claris FM Cloud. In this blog post, we’ll focus on FM Server.

As you continue through the configuration of this trigger, you’ll be prompted to “Sign in to Claris FileMaker Server.” Note that this is not a prompt to log into the server itself but rather into a specific database on that server. Enter your Claris FileMaker Server’s domain address and the username, password, and database file that you plan to use to trigger the Flow. The username and password are the credentials used to log into the database file specified. Be sure to use a database account that has Data API access enabled in its extended privileges.

Your New App Connection

A great feature to note here is that once you successfully configure this connection to your database, it will be available as an “App Connection” to use in any other Flows within the same Project

Generating Your Callback URL

After logging into the database on your Claris FileMaker Server, a callback URL will be generated along with a list of instructions for setting up the script within your Claris FileMaker solution. Note that the language is somewhat misleading here: It says, “Create a FileMaker Pro Script trigger for Claris Connect.” However, this does not mean Script Trigger as we know it within FileMaker, but rather a regular FileMaker script that will function as a Claris Connect “trigger.”

4. Create the FileMaker script per the instructions. If you’re using Claris FileMaker 2023, you can use the new script step “Trigger Claris Connect Flow.” Otherwise, you can accomplish the same thing using the “Insert from URL” script step instead. See examples of both methods below:

As you define the $json_data variable, if you’re using Insert from URL, make sure to include the “action” property – this is required – set to “script.” This is not required with the new Trigger Claris Connect Flow script step. You can add additional JSON objects to the JSON variable, even values to be processed by Claris Connect for another API connector in the Flow. These will be available throughout the Flow as what Connect calls “Step Data,” which you’ll see an example of in a moment. We are going to add a “message” property like this:

5. Test and save. Run the script in your Claris FileMaker solution. You should receive a “Success” message in your Claris Connect window. Finally, click “Save Trigger.”

Add the SNS Action to the Flow

In Claris Connect, add a new action to your existing flow by clicking “+” to the right of the “Trigger by script” action.

Search for “SNS” and select “AWS SNS” in the resulting list.

You will see the handful of actions that you can perform with SNS through Claris Connect. Select “Publish Message”.

(More info about the “Publish” action is available from the AWS API documentation: https://docs.aws.amazon.com/sns/latest/api/API_Publish.html)

Click “Sign in to AWS SNS.” Then enter your access key and secret access key that you saved in the “Setup AWS Application-Specific Account” phase.

On the Configuration view (shown below), check if the Region you have set for your AWS SNS topic shows in the dropdown. If not, you can select “type a custom value.” One challenge we ran into when using a non-default region was formatting the region name inside Claris Connect. For example, say you want to use “US East (Ohio)” for your region, but it isn’t in the dropdown list. You need to select “type a custom value” from the dropdown list. Then, enter the region as “us-east-2” instead of “US East (Ohio)” to properly configure a custom region value.

For the ARN field, the dropdown list should contain the ARN for the SNS topic “Claris-Connect-To-SNS” that you created earlier.

Setting Your Default Message

In the Default message field, you can type any text you like. However, here you can also use Step Data, as mentioned earlier. Clicking the button to the right of the field will open a popup listing the previous steps in the Flow. In this case, there is just one “Claris FileMaker Server” step. Clicking on that will expand to show you the key-value pairs from the JSON that you passed via the triggering FileMaker script. Select the “message” element. You’ll see that “body.message” gets added to the Default message field:

Run It!

Finally, we are ready to roll. In Claris Connect, ensure you’ve enabled the flow with the blue toggle switch on the upper right. Then, run the script in Claris FileMaker to trigger the Claris Connect flow. There are a few ways to check for success:

1. Run the script with the debugger and inspect the $response variable in the Data Viewer. It will show “OK” if the triggering step ran successfully. However, take note that this is just the result of a “fire and forget” action. It only indicates the success of the script but offers no further information on whether the message was actually published.
2. You should receive an email message from the subscribed topic in your inbox, with the “message” data in the body. (Remember to also check your junk folder.)
3. Check the “History” tab shown at the top of your Claris Connect flow. This area displays all the attempts to run the flow along with either a “Success” or “Error” status. You can then click into it to inspect. We’ll explore the History tab in more detail in future posts.

Moving Forward with Claris Connect

Using Claris Connect to leverage services available through AWS can eliminate the need for complicated API integrations and reduce code in your custom application. We’ve shown how you can use a Claris FileMaker script to trigger a Connect flow and initiate a basic SNS action. While this may be enough for some purposes, it has some limitations. Most notably, it cannot obtain a response from the flow due to the “fire and forget” nature of the Claris FileMaker Server trigger.

In the next post in this series, we’ll demonstrate how to improve the SNS implementation by using Claris Connect’s HTTP utility instead of the “Trigger by script” trigger we used here.