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
Error trapping and handling are critical aspects of every computer program. Flows created using Claris Connect are no exception. This blog post will cover how to capture any errors that might occur when executing a Claris Connect flow. We will also cover how to exit our flows with an appropriate representation of such errors.
What Errors Look Like in Connect
The “History” tab is your friend when troubleshooting any issues with a Claris Connect flow. You can access the History tab at the project level, in which case you will see one entry for each time a flow within that project has been triggered:
Conversely, you can select a specific flow first, then switch to the “History” tab from the context of that specific flow. You will then only see entries for calls made to that flow.
Note that when you create a new project, the option to save request and response data is off by default. Be sure to enable this option at the bottom of the “History” page.
The “History” shows each time a flow was executed and if it succeeded. It also shows what version of the flow was active when it was triggered. (Connect automatically keeps versions of a flow as you save changes.)
For demonstration purposes, I’ll stick to a flow that uses the AWS Simple Notification Service (SNS) Connect connector to publish messages via SNS. I’m using an AWS SNS flow to be consistent with the type of flow covered in previous blog posts:
- Using Claris Connect with AWS Simple Notification Service (SNS)
- Implementing custom responses in a Claris Connect flow
The concepts covered in this post, however, apply to any flow using any Connect connector. The first use case I’ll cover is when the application triggering the Claris Connect flow expects a response upon completion. In this scenario, the webhook for the Incoming HTTP Request trigger has the “Return sync response” option enabled.
Revoking SNS Access to Force an Error
To force an error in my demo SNS flow, I revoked SNS access to the Identity and Access Management (IAM) user used in the flow’s “app connection.” The “app connection” stores the credentials to authenticate against AWS SNS.
Then, if I trigger the SNS flow to publish a message, the flow fails, as expected. We can then look at the failed entry in the “History” tab of the Claris Connect flow. Under the “Publish message” action and “Response” section, we see the Publish action failed with HTTP code 403 (Forbidden error). The error message states that the user credentials the flow uses to talk to SNS are not authorized to publish a message. This, of course, is because I revoked the policy that allows SNS access from the IAM user.
Executing the Flow from a Claris FileMaker App
If we had executed this flow from a Claris FileMaker app, the FileMaker script would have stalled at the “URL Data Transfer” popup. We have covered that situation in previous posts in this series on AWS and Connect blog posts. Because an error occurred when publishing the message, the third step in the flow, “Reply with JSON data,” is not executed. The flow then ends without returning an http response.
The way to determine if an error occurred or not and to branch accordingly is to use the “On Error” action.
On Error Action
Using the plus icon to the right of the “Publish message” action, select the “On Error” action. This action has no fields that we can edit but will make error data available to the next action. After the “On Error” action, add another “Reply with JSON data” action. The step data available from the “On Error” action in this case is this:
The screenshot below shows how we can use the step data from the “On Error” action in the custom JSON response. Note that I renamed some default action names to more meaningful ones. To rename an action, hover over the plus icon on the right of the action and select the “Rename” option. Note that not all actions can be renamed, e.g., “On Error” cannot be renamed.
If an error occurs, I exit the flow with the same HTTP status code and error message that the “Publish message” action returns. Note the indentation in the actions that Connect creates automatically. You can see this more easily in the collapsed flow shown in this screenshot:
The indentation conveys that if an error occurs after the “Publish message” action, the “Custom error response” action will be executed. Conversely, if there is no error, the “Custom success response” action will be executed.
If calling this flow from a FileMaker app, we would see something like this in the Data Viewer:
The 403 HTTP status code is part of the HTTP response header. which we capture using cURL options in the “Insert from URL” script step. (See blog post Implementing custom responses in a Claris Connect flow for how to do this.) The error message originally returned by SNS is captured in the $response variable, which we specified as the “Target” in that same script step. W e grabbed this error message from the “On Error” action’s step data.
If-Then Action
You might think you can use the “If Then” action to capture errors instead of the “On Error” action. However, if we add an “If-Then” action after the “Publish Message” action, the step data for the “Publish message” action does NOT include error data. Instead, it includes the data from a previous successful flow execution. Example:
To trap for errors, we need to use “On Error.” However, depending on a given business workflow, it may make sense to follow an “On Error” action with an “If-Then” action. For example, we could choose to inspect the error data in the “On Error” action, and depending on the nature of the error, the flow could fork accordingly. The following screenshot shows how, after the “On Error” action, we can have an “If-Then” statement in which we inspect the HTTP status code. If the status code is 403, we return a custom JSON response in which we overwrite the original error message. If the status code is anything else (the “then” portion of the “If-Then” action), we return with a different custom JSON error response. When there is no error, as before, the flow exits with the “Custom success response.”
Handling errors When Using a Fire-and-Forget Type Trigger from FileMaker
How we have handled errors thus far applies to the scenario in which the application calling the Connect flow waits for an HTTP response when the Connect flow completes. Let’s now consider the scenario in which an application makes a fire-and-forget type call to a Connect flow, and that application only needs to be notified if an error occurs.
This could be handled different ways, depending on the business needs. We could, for example, use another Connect connector, such as Outlook, Slack, AWS SES, etc, connectors, to send an email or text message error notification. Alternatively, if the calling application provides a callback webhook, we could use the Connect HTTP utility to make an “HTTP POST request” to that webhook.
For the sake of this post, we will demo how to asynchronously send an error notification back to a FileMaker application that makes a fire-and-forget call to a Connect flow. We can do this using one of the Connect Claris Apps, such as “Claris FileMaker Cloud,” “Claris FileMaker Server,” etc., depending on the organization’s particular FileMaker setup. Regardless of which Claris app we use, we have a couple of options for notifying FileMaker of an error. We can use the “Create record” action to create a record in a “Log” or “Errors” table, which would then have to be parsed. Alternatively, we can use the “Execute script” action to call a FileMaker script. I tend to favor the latter because I find it more flexible. As part of the script that gets executed, I can perform various tasks, including creating an error log record.
Use Run Script Action to Notify FileMaker of a Flow Error
In the scenario we are exploring now, the “Return sync response” option is disabled in the webhook used by the “Incoming HTTP Request” trigger. We could add a Claris app “Run Script” action right after the “On Error” action in the new flow. That would be just fine and may satisfy your needs. But let’s say we have multiple Connect flows within a project, and we want to handle any errors from those multiple flows in a centralized location. In such a scenario, instead of having “Run Script” actions in each flow, we may choose to have a dedicated flow that, in turn, is called by other flows to centrally handle errors. Then, if we need to change any aspect of that “Run Script” action, we have a single action to update instead of needing to do so in each flow. That’s the approach I’ll demo next.
Creating a New Flow
Start by creating a new Webhook, enable the “Authentication” option, and leave the “Return sync response” option disabled. Then, create a new flow with an “Incoming HTTP Request” trigger, just like in previous blog posts. Select the newly created Webhook in that trigger. Then, add a “Run script” action after selecting the relevant Claris App for your situation. Choose the relevant layout and script to execute. Then use step data from the trigger step in the “Script parameter” field.
The new flow should look something like this:
Now that we have our callback flow setup let’s look at a modified version of our SNS flow. This flow version does NOT return a response. Rather, if an error occurs, it uses the “HTTP POST request” action in the HTTP utility to call our error handling centralized flow (see screenshot):
Authentication
Since we enabled authentication for the callback flow’s Webhook, in the “Authentication” field in the “HTTP POST request” action, you can enter the AppID and the APIKey separated by a pipe character, i.e., <AppID>|<APIKey>. The Authentication field is not shown in the screenshot. The other two fields in this action, File and Header, are not shown either and can be left blank.
In each of the flows in our project, we can have a similar “HTTP POST request” action that captures the specific data for the error(s) that can occur in that flow. That error data is packaged as JSON and sent as a POST request to our dedicated error handling flow. The error handling flow, in turn, passes that error data to a FileMaker script.
The simple FileMaker script I wrote for this demo creates a record in the “Log” table and sets a “payload” field in that table to the passed parameters. Here is a sample record created in my demo FileMaker file:
Stop Flow Action
For completeness, I’ll briefly mention the “Stop Flow” action. Depending on the flow, it may make sense to add a “Stop Flow” action after an “On Error” action. The “Stop Flow” action does as its name suggests: it stops the flow. Optionally, we can display an error message to the user via this action.
Moving Forward with Claris Connect
Claris Connect provides tools to trap for and handle errors in our Connect flows. Unhandled errors can result in data loss, broken business workflows, missed notifications, etc. Whenever you create a Connect flow, I strongly encourage you to put a robust error trapping and handling mechanism in place. This ensures that if any aspect of your flow ever behaves in an unexpected manner, your flow will handle an error condition gracefully, and you and/or users are notified appropriately. 
Our experienced team members can help you explore, understand, and leverage Claris Connect. Contact us today to learn more.
