Claris FileMaker Add-ons: Refining the Find

We’re continuing our discussion of the new FileMaker 19 add-ons. Claris has released a great video on these add-ons, but, in this series of posts, we’re taking a deep dive into how the add-ons work. In this post we look at the FileMaker Add-ons Find mechanism.

FileMaker Add-ons Find Mechanism

By default, each ‘dashboard’ add-on returns all or most of the data in the target table. For the Kanban, the add-on will display all the tasks in that table. The Calendar add-on will return a found set of events: those events in a three-month time period where today is the center of that. And for most uses and users, that is fine.

You can certainly adjust the filter of an add-on to return a different found set. However, there are folks (you know who you are!) who want to dive deep into all parts, including the find. So let us help you understand what’s happening in the find.

Setting the Stage

In the information-gathering set of steps, the script gathers the important information it needs to process the find. It starts with the $json, a script parameter sent from the add-on to FileMaker. Here’s a description of each of the variables:

The $data is the basic query that will be used in the Execute FileMaker Data API script step. It was constructed by the JavaScript code and includes the target layout, primary key field, and any other fields used in the query. All of the fields are set in the configurator. Here’s what the Activity Timeline’s query looks like.

{
   "layouts":"ActivityTimelineSampleData",
   "limit":500,
   "query":[
      {
         "ActivityTimelineSampleData::PrimaryKey":"*"
      }
   ],
   "sort":[
      {
         "fieldName":"DateStarted",
         "sortOrder":"descend"
      }
   ]
}

Since this value in $data is just JSON, you can easily update it on the fly via the script. If you want to return more than the limit of 500 records, adjust that. If you want to add more filters to the query, you can do so.

$Callback contains the name of the JS Callback function that will run. There’s no need to update or change this.

$FetchId contains a UUID for the JS code and this fetch. There’s nothing to see (or do) here.

$AddonUUID is the unique identifier of the add-on that is triggered.

$Config contains the config for this add-on. Though it is stored in a FileMaker field, this config object is also part of the add-on and is used all over.

Adding the Filters

In the next set of steps, the Config-set filter is added to the query. This, of course, happens only if there’s a filter value.

Performing, Getting, Sending

In the last section of this script, the query is performed using the Execute FileMaker Data API script step. The response is checked for errors, and, if no error, the response is sent to the add-on.

Here’s where the $Callback variable gets used. This JS Function replaces the data in the add-on with the new found set.

Possibilities

This Find process works just fine as it is, but there are possibilities to refine it. As a FileMaker developer you know what you’d need to do, but the basic idea is that you update the find query. The filter mechanism is a user-facing possibility, as you have a field that contains a find criteria. But you could easily update this script to include hardcode something into the find, whether it’s to return user-based or security-based or any other kinds of constraint.

Most of the script shouldn’t really be altered, but here are the few places:

• Update the $data query on the fly, adding or updating JSON elements.
• Add to the Query filter if you want, or change it.

That’s really it. This find script is there to gather data, and really it should be left alone as much as possible. The script name shouldn’t be changed, and of course, don’t delete it.