FMPerception’s realtime developer intelligence is essential for developing. We’ve mentioned that many times. But it’s also good for talking with others about systems and about development practice. Let’s listen in on a FileMaker code review run by a MENTOR with her MENTEE using FMPerception.


INT. Day. MENTOR’S computer. She starts up the meeting. MENTEE Joins.

MENTOR: Hello?

MENTEE: Hey there.

MENTOR: How was your weekend?

MENTEE: Oh it was fine. Spent most of the weekend studying for my certification test. It’s coming up soon.

MENTOR: Ah yes. Well we can chat about that if you want later, but first let’s do some FileMaker code review using FMPerception on your latest project.

MENTEE: Sounds good. I look forward to it

FMPerception in a FileMaker code review

MENTOR: This morning I ran a DDR and loaded it into FMPerception to–

MENTEE: When did you run it? I was working on it this morning.

MENTOR: Oh. Ok. Well let me run the DDR again and load it into FMPerception again. Should just take a few moments. In the meantime, I’ll share my screen. There. Can you see my screen?

MENTEE: Yep. Woo. FMPerception already loaded the DDR. That’s pretty quick. It took like five seconds.

MENTOR: It really is. I use this probably twenty times a day to analyze the files I’m working on and look for something like a script or variable or whatever.

MENTEE: Cool. I should use it more.

MENTOR: Yeah. It’s useful for a developer. Okay. So now it’s loaded I want to review a few things with you. First did you have any questions about your file or specific scripts or workflows?

MENTEE: Well I did want to ask about script and layout organization. I’ve not been putting them into folders and wanted to know what you thought about that. And, um, I’m not sure what else.

MENTOR: That’s okay. We will take a look at your folder structure in a bit. Let’s turn to FMPerception and your file.

Report card

MENTOR: In the FMPerception report I pulled up earlier I noticed a few things and wanted to mention those. First, the Report Card for the file shows a lot of good information. This report, as it says next to the name is slow, but the slowness is just a matter of a few more seconds than the rest of FMPerception.

MENTOR: Here it is. What I notice first is that across the top you’ve got 156 unreferenced and 256 broken references. That’s quite a lot. We should probably get those numbers down. Broken refs could disrupt the intended workings of the file, and unreferenced just might be making the file bigger than it needs to be.

MENTEE: That’s a lot of broken references.

MENTOR: Well it could be many things. When I ran the DDR it was missing a few files.

MENTEE: Yah. Those were taken down temporarily while Fred works on those.

MENTOR: Okay. And as I review the broken references details I see a lot of them, about half, are <function missing>. I must not have the plugin. So no big deal. Others, like “Empty Layout Reference” might need some fixing.

MENTEE: Got it. That’s useful. I wouldn’t have known where to find the broken references. FMPerception shows them pretty well.

MENTOR: It looks like some of the scripts are missing all their tables.

MENTEE: Oh yeah. I imported that script and haven’t finished setting up the references. I keep forgetting that I should import the table first, then the script.

MENTOR: Doing that would resolve the links. You could simply delete this script, copy the table from your sample file to this file and then paste the script back in.

MENTEE: I’ll do that.

Global variables

MENTOR: Moving on. I wanted to review your use of variables. You’re using only a handful of global variables. Global variables are fine to use; they just get tough to trace sometimes when they’re set or used in many parts of the file. Luckily we can see the information here and click on any number to take a look at the details. I can click on “Impacted Layout Objects” and see, in your case, the six items that are affected by a global variable.

MENTEE: Should I not be using global variables?

MENTOR: I think it’s fine to use them. Just be aware of them. I wouldn’t use them to store any security-related information, but otherwise they’re fine.

MENTEE: I don’t follow.

MENTOR: Many developers use global variables to store certain privilege information or other settings. If many of the scripts in the same file have logic in them that depends on the values in the global variables, it would be very tough to track all those down. FMPerception shows you everywhere your global variables are used so you can better track those down.

MENTEE: Okay. So use global variables, and use FMPerception to keep tabs on them.



Standard script steps

MENTOR: I poked around in other areas of your file. The “Standard Scripts Steps” section of FMPerception. What do you notice about this report?

MENTEE: Hmm. You clicked on “Set Variable” of my Clients file. On the right and in the pane below I can see all the times that is used. I can see the details of the step and its script name and even the line number.

MENTOR: What else?

MENTEE: What’s that “Button” designation?

MENTOR: That’s shows every time the Set Variable step is used in a single-step button.

MENTEE: Oh yeah. Wow. That’s cool. I can see here I’ve got three buttons that perform this step. I wonder if I should turn those into scripts…

MENTOR: I would. It’s certainly harder to debug or change these steps.

MENTEE: I’ll get on it.

Single step buttons

MENTOR: You can use the “Single Step Buttons” line on the report card to track down all of the buttons that do a single step and update those. This section shows you: (1) the layout this single-step button it is on, and (2) the coordinates and region it is located. You may want to review the steps beforehand. If many buttons do the same thing, such as “Delete Record/Request” (3), you can create a script that does that one step and assign the script to many buttons. This report shows a lot more buttons that perform single steps. Use it to eventually clean those up.

MENTEE: Got it.

Standard Functions

MENTOR: Moving on. The Standard Functions area is similar in reporting. Here we can see all the uses of each of the standard functions. Like the Standard Steps, this section shows only those functions you’ve used in the file. You can use the Search bar to find any function you’d like.

MENTEE: I like this. Oh. I can use it to look up my uses of ExecuteSQL.

MENTOR: That’s right. You can see the count here, click on the function and see all the places it is used.


MENTOR: What’s more, FMPerception treats ExecuteSQL specially. This function is a common performance-issue creator, so FMPerception has a special column just for that when you view all the script steps. The dot here in the row indicates this step uses the function. After sorting by the ExecuteSQL() column and all the steps that use this function are sorted to the top, I can look through each one. So far you’ve only used the function one time.

MENTEE: Ah. Interesting. I like using ExecuteSQL.

MENTOR: It’s useful but can cause issues in performance, so use it, but be aware of each use and any implications. And, of course, there are many other ways to get the same result. FMPerception has this separate ExecuteSQL() column in many sections: Scripts (flat), Steps (flat), Layouts (flat), Layout Objects, Table fields, calculations and other places where ExecuteSQL could be used.

MENTEE:  My first DevCon was in 2012.. I clearly remember sitting in the audience by myself and listening to one of the presentations. ExecuteSQL had just been introduced and the presenter was gushing over the fact that he was able to reduce the number of table occurrences by a huge percentage using ExecuteSQL. Everyone applauded. There were gasps.

MENTOR: I remember that. ExecuteSQL is great, but its performance considerations are worthy of thought. In most cases adding a table occurrence and relationship, if you keep the graph organized, is less of a performance impact than using ExecuteSQL in the wrong place. I’m finding I use ExecuteSQL less and less. There are other ways to get the data I need.

MENTEE: I like using ExecuteSQL, but will explore other ways to return lists.

Take a break

MENTOR: Great. Hey. Can we continue in just a few moments? I have to step away. Let’s connect again in 15 minutes. Okay?

MENTEE: Okay. Sounds good. Talk in a few.


Realtime developer intelligence code review

The mentor and mentee took a break. We’ll get back into their conversation in the next post. As you can see in this first half, however, FMPerception is useful in a code review. The conversation centers around objective facts found in the intelligence tool. The mentor can spot bottlenecks or potential issues, and the mentee can use the facts to improve his code.

Let’s get back to the FMPerception FileMaker code review in the next post.

FileMaker Transactions give us the complete tools we need to ensure records are completely created, edited, or deleted. We’ve seen in a previous post the idea behind it. Let’s now take up the idea of starting a FileMaker transaction. Our Karbon framework goes to extensive lengths to start the transaction, but your process can be pretty simple. Check out Karbon or look at the transactions module on Both are great examples of the entire transaction process.

Starting context

It’s important to get started on the right foot before a transaction begins. We need to begin the transaction from somewhere.

In Karbon and in the Transactions module, we use a DBTransactions table.

It contains fields for logging the transaction’s data, start and end times as well as any information about the success or failure. And it contains fields which are used for the relationships to tables in which records will be created or edited or deleted.
If you use the DBTransactions table, it is the starting context for every transaction in your entire custom app. It’s helpful to have all of them start at one place.

But your starting context can be any context that makes sense. If the use case is to copy Estimates and estimate line items to order and order line items tables, you could use the Estimates context as my starting point. If you need to copy estimate #4392 to an Order record, your starting point is Estimate #4392.


The starting context contains fields that are used in relationships to the tables where data will be added or edited. All the relationships are set to “Allow Creation of records in this table via the relationship”.

The DBTransactions starting context.

The Estimate starting context

In the starting context table I’ve got two fields, “TR_OrderId” and “TR_OrderItemId”. These fields are related to the primary key fields of the respective tables. We use the primary key fields because the relationship needs to be unique per record we will create.

Collect the data

Of course it’s always good to collect the data that will be added or edited. In the example we are following (copying estimate to order), we could collect all the data, both the estimate record information and each estimate line item data as a JSON object and store that somewhere temporarily. This gives us confidence that the data we have stored is correctly synced with itself. It is one complete object and one complete record. Once it is stored, changes can’t be made to individual fields in this one estimate record.

In our current example, if the starting context is indeed the Estimate record, then we don’t really have to collect the data since it’s already in the current record.

Validate and take ownership

Additionally we might want to validate the data. We want to make sure there is actually data to process and that there’s no errors in the data.

Also, we want to take ownership of the vital records. I don’t want anyone to edit the Estimate record and EstimateLineItem records while I’m copying its data to the Order table, so my process needs to own the record (lock it) during the process. If we’re editing records, it is possible to lock each of those in the starting process. So we open the Estimate and individual line items records.

Call a start transactions script

In Todd’s post about Transactions long ago, he states that there is no ‘start transactions’ script step that we can run. But we can put all of the starting tasks into a subscript and call this at the start. Our Karbon framework contains a script called “Start Transaction”. This file set and the transactions at are good models for the script.

Any additional tasks

If you’re using the DBTransactions (or something similar) you might find it useful to create a new record for every transaction process (the entire process: creating all records in the order and order line item table). You can record the binary result of the process: did the transaction go through or was it rolled back.

The process to start a FileMaker transaction is fairly straightforward. Whatever the details, this step sets up a likely successful transaction. The process gets all the ducks in a row before the transaction takes place.

In the next post, we’ll talk about the transaction process itself.

A big part of our work as FileMaker developers is to design workflows that create or edit or delete records. If your scripted process requires that it completes the changes (adding or editing or deleting) to multiple records, then a database transaction is required. If a discrete entity (an invoice and invoice line items, for example) needs to be completely changed, then a database transaction is required. Let’s take a look at how database transaction works so that we can have confidence in FileMaker data changes.

An example to consider

Let’s imagine a custom app for a printing company. They create estimates with estimate lines.

The business workflow requires an estimate and its lines be copied into the order and order line items tables respectively. Here would be a typical script we might write.

There are issues with this script. Take a moment to study it. Based on what I’ve written above, what problems do you see?

I’ll wait. 🙂

The biggest problem is that I’m committing the new order record and the new order line items records individually. Here’s the sequence of events:

  1. I go to the Order Table and Create a record
  2. I go to the Order Line items table. In this action, the Order record gets committed
  3. I create a new record in Order Line Items table.
  4. After the first iteration of the loop, I create a new record. That commits the previously-created line item record.

We can see this commit after commit after commit happening. In the Data Viewer, Get(RecordOpenCount) shows 1. There’s only one record open. The previous records have been saved to the file.

If, while the script is running, the power goes out or the network collapses, some of the order line items records will have been created; others won’t.

That’s a problem, right?

The solution

FileMaker is a transactional database platform. A transaction is the complete process of getting records created or edited or deleted. The process is set up so that all records get saved to the file after creating or editing. The process is also set up to rollback changes made to records. The transactional model gives us peace of mind to have confidence in our FileMaker data

Commit all records

Your goal as a FileMaker developer is to provide a trusted workflow that keeps a user’s data intact and complete. Transactions ensure that all changes you made to records in the database get committed and saved to the database at once.

Rollback records

If there’s an error anywhere–power loss of incomplete data or record ownership issues–FileMaker Transactions rollback the data to their previous state. The changes (additions or edits or deletes) made against records, using a transactional model, do not get saved. The Pre-saved data is kept.

Transaction steps

The complete steps of a transaction are as follows:

  1. Start the transaction
  2. Create or edit or delete records
  3. End the Transaction

We can do all of these in FileMaker, and none of them are that difficult that even a new-to-FileMaker person cannot handle them. I’ll briefly explain these and then we’ll look at these in more detail in further posts.

Start the transaction

To perform the transaction, we need to start it. We get the correct context to the front, we get up the data to be added, and just get ready. The start step can include any of the following:

  1. Go to the proper transaction layout
  2. Validate the data to be added or edited.
  3. Create or open the transaction record. Record any transaction log information.
  4. Take ownership of records.

No matter the steps we take here, the last one is to continue or stop the transaction process if something’s not right.

Change multiple records

Once the transaction has started and we can continue, we add the records, edit the records, or delete the records.  This is the easy part. It’s what we script for every day. We’ll talk through this in detail in an upcoming post or tw.

End the transaction

In the transaction’s ending we:

  1. Try to commit the record changes made
  2. Check to see if there’s any errors
  3. Revert the records if there’s any errors
  4. Optional: Clean up. Record the success (or failure) and any other information about the transaction.

Transaction structure

There’s a simple structure to FileMaker Transactions. It requires just a few things:

  1. A Starting context
  2. A relationship to table occurrences in which records will be added. This relationship is set to “Allow Creation of records in this table via the relationship”.
  3. One or more scripts that control the record creation or editing or deletion and prevent any commit of records accidentally.

Have Confidence in your FileMaker data

Okay. This is enough for now. It’s a process, and one that deserves a through discussion. We’ll talk in the next few posts about the three steps: starting the transaction, doing the transaction, and ending the transaction. We’ll talk conceptual and practical. The whole point is to have confidence in our FileMaker data, to make sure that all of the changes get made or none of it. This topic merits more details. So we’ll talk through it here in upcoming posts. Stay tuned.

WidgetStudio gives all FileMaker developers a break. The dev tool solves a simple or complex FileMaker use case by making a web viewer widget that just works. It saves the developer brain power, frustration, research, and lots of trial-and-error. There are useful widgets available right now in WidgetStudio, and many more on the way. The tool was developed by a FileMaker developer. It is designed to give FileMaker developers the most FileMaker value add to their development of client custom apps.

The benefits to using WidgetStudio are legion:

  • You can solve a use case faster.
  • A widget brings a lot of functionality and modern user-interface elements.
  • The deployment process is painless
  • There’s little to no testing involved.
  • The widget you employ can be customized to any client app and data.
  • The Widget you employ can interact directly with FileMaker data
  • You don’t need to know how any of it works.

Let’s dive in and see how WidgetStudio brings value add to your development process.

Solving use cases faster

First, every single widget so far in WidgetStudio solves a typical case for FileMaker developers. Nothing’s in there that is superfluous.

  • When a client asks for a portal-like list view with column sorting (including multiple columns), as-you-type filtering, and pagination, the DataTables widget is your solution.
  • When you need to chart a lot of data, all the charting solutions are useful.
  • Progress bars can show the progress of a project.
  • A Data tree can be used to show data in a tree.
  • And there’s many more.

The value add by WidgetStudio is that these widgets are created in a very short amount of time. There’s really no comparison. Creating a pivot table using ‘idiomatic FileMaker’ would take hours.

WidgetStudio includes complex widgets that would take a lot of time to create in FileMaker.

I can deploy a pivot table using WidgetStudio in under 15 minutes. The time I saved by deploying a widget can be then spent on additional features or additional scope. That’s a lot of FileMaker value add.

Full functionality

Second, each of the widgets in WidgetStudio is a complete feature set. Much of it exactly what we can use in our custom apps. The Date & Time picker, for example, contains all the text and buttons and code and styles to select one date or a range of dates.

This library comes with additional functionality that allows for custom date ranges.


The value add comes in that in the single deployment from WidgetStudio, a FileMaker developer has ‘created’ all necessary UI elements and functionality. In one button click.

Painless deployment

I’ve written about this before. And believe me: I’ve experienced all the ways possible to deploy a web viewer widget. Nothing comes close to the ease by which WidgetStudio deploys a widget.

Again, the FileMaker value add comes in the little time it takes to deploy. But so too is there value in the way widgets are deployed. There’s no extra schema or fields or relationships necessary. There’s zero to one script and the web viewer object. That’s it. This object and the script can be placed anywhere in your app.

Another value-add factor: I have absolute control over the widget. Of the three deployment methods, two of them create the script steps necessary to load the widget. I prefer that. I prefer to control everything with scripts.

It just Works

The JavaScript library was built by a JavaScript developer and has been tested hundreds of times. Most or all of the bugs been worked out, so we get a widget that is very much bug free. The value add here is simply the time we get back not having to test EACH SCRIPT that is part of the widget.

Customizations galore

WidgetStudio’s interface is brilliant as it provides a clean, simple way to customize the options of each widget.

You don’t have to dig into the CSS to change the font or the size or color of the text. It’s a simple few options. The value add here is (of course) the time saved, but also the success you’ll get in customizing the widget and seeing the results.

Interact with FileMaker data

Furthermore, WidgetStudio makes it simple to pass data from the widget to FileMaker. It just works. You set up the name of the file and the name of the script to run, and WidgetStudio sends the data back in the form of a JSON object to FileMaker. There’s plenty of information in the widget to let you know what to expect. And WidgetStudio can even CREATE the script steps for you. Do you see the value add here?

You don’t have to know anything about it

And finally, the biggest FileMaker value add to a developer is that all the above benefits just work, and you don’t need to know about it.

The lack of knowledge isn’t because the workings aren’t a secret like a magic trick. Instead a FileMaker developer doesn’t need to worry about any of this. She doesn’t need to think about much of it. This frees her up to consider other things. We exert a lot of brain power during normal development. A Filemaker developer can use the brain power she saved to puzzle something else out

WidgetStudio: FileMaker value add

WidgetStudio provides much FileMaker value add to your development. You’ll be able to add a complex, fully-functional widget that solves use cases. And WidgetStudio solves them faster.

Check out the demo of WidgetStudio. Experience the strong value add to your development time and success.

Last week we introduced a game-changing app in the FileMaker & JavaScript space. WidgetStudio makes it so simple to add simple or FileMaker web viewer widgets to your custom app. From pivot tables to charts, WidgetStudio allows you to find or create, customize, and deploy the widget in a matter of minutes.

Find widgets

The WidgetStudio demo has three FileMaker web viewer widgets included that you can use to play with and see how the app works. But beyond that, there are more than ten other widgets that are available for WidgetStudio users (licensed and demo users) to view and customize.

Licensed users can deploy widgets from the library, but everyone can see what we have.

Here’s what we have so far.

More widgets on the way!

These eleven widgets are available now for review and deployment (with a licensed copy of WidgetStudio), but we won’t stop here. Over the coming weeks and for the foreseeable future, we plan to release widgets through the repository. So stay tuned to Geist Interactive and WidgetStudio on Twitter to get the latest.

If you have an idea for any FileMaker web viewer widgets, be it a JavaScript library or just a FileMaker use case, send it our way and we’ll try to create that widget.

Additionally if you want to make your own widgets, you can. Feel free to submit the widget to us to add to the repository.

WidgetStudio is a tool

Like a hammer, you go out and buy the hammer. You pay for the tool. What you build with it is up to you, and the hammer store doesn’t charge you for what you build. Likewise, WidgetStudio is a tool that has an annual license. How you use WidgetStudio is up to you; there is no additional charge for use of the widgets.

Use FileMaker web viewer widgets everywhere

WidgetStudio allows you to distribute FileMaker web viewer widgets in a few ways.

  • You can share a widget exported from WidgetStudio (as a .json file) with another developer.
  • You can deploy a widget using an embedded web viewer or through a script.

These royalty-free methods of distribution are completely independent of WidgetStudio. They will work regardless of WidgetStudio’s presence or active status. The widgets will continue to work in your system systems.

License options

We provide four license options of WidgetStudio. These licenses have everything to do with the number of computers that uses WidgetStudio. No one who simply uses a deployed widget in a custom app needs a license.

The power of FileMaker web viewer widgets

WidgetStudio gives any FileMaker developer access to powerful widgets that can be used in any custom app. We use them. Join us and check out the demo of WidgetStudio to give this power a try.

FileMaker is a complex platform. There’s FileMaker Pro Advanced, FileMaker Go, FileMaker WebDirect, FileMaker Server. We also have FileMaker Cloud, FileMaker Data API, Custom Web Publishing, and Runtimes solution. There’s a lot to the platform, and we, as developers need to know what works for each component. We should know as much as we can about FileMaker Script Steps and their compatibility to those parts of the platform we are targeting in our development. The best place to learn about script steps is in the FileMaker Script Steps Reference.

Very Helpful Help

As I’ve written in a few other posts (FileMaker Help and FileMaker Functions Reference), the FileMaker help system is vastly improved from years ago. There’s a lot of information inside each page. The folks at FileMaker, Inc. put a great deal of effort into the pages. It is very much worth our look and study.

The FileMaker Help Script Steps Reference Page format

Each script step is well document with the following sections:

  • Name
  • Options
  • Compatibility
  • Originated In
  • Description
  • Notes
  • Examples


This section describes all the possible options you have with a script step, which are found inline (for boolean options) or in the gear icon. The more options, the more information there is here to read and understand.


Each script step has one of three compatible choices for each part of the platform: Yes / No / Partial. Here’s what the Sort Records Script step’s compatibility looks like.

Originated In

While seemingly benign, this section tells you if you can use a script step. As you read about techniques or get answers from the community, you should review it to see if you can use the step. Of course, if you’re on the latest version, there’s no problem. This section then becomes a cool FileMaker-trivia source.


Here is where the script step’s purpose is described. It’s pretty straight forward, but one that should hold our attention. For example, the Sort Records script step description has this line.

 If you sort a repeating field, FileMaker Pro Advanced sorts on only the first entry in that field.

I didn’t know that. But I never use repeating fields for data-storage, so I guess it’s okay not knowing this 🙂


This section is worth its character count in gold. Here we can read some of the nitty-gritty details about the script step and learn why the script step has Partial compatibility in a part of the platform. For example, the Sort Records script step has partial support in FileMaker Server (scheduled scripts or Perform Script on Server). Here’s what it says

Server-side scripts, the FileMaker Data API, and Custom Web Publishing run this script step as if the With dialog option is set to Off, so you must use the Specify sort order option to save the sort order in this script step.

Again. Interesting and vital to our development. If this script steps doesn’t have a sort order specified in the step, the server-run script may end up with the wrong order of records.

I take my time to read and understand the Notes section. There’s valuable information here that might apply to us. I appreciate FileMaker, Inc. taking the time to write out these minute details.


The script step in question is shown in an example. There’s a brief narrative of what the script should do, and then the steps are listed. It’s a good source if you’re learning about the step.

It’s Worth the Look

The FileMaker Script Steps reference has much value to FileMaker developers. Many script steps have individual quirks about them, which are documented here. FileMaker developers new to the platform would do well to read the help while writing scripts or reading an answer on the community. Experienced developers could refine their understanding of the script steps. And, while unconfirmed, I’ve heard that many questions on the FileMaker certification test come from the “Notes” section of the steps.

When you need a break, when you’re stuck mid-script-write, or just want to waste time, read through a script step’s help. You’ll probably learn something new.

I’m pretty fascinated by the FileMaker help system. Specifically the FileMaker script step and functions pages. They are packed full of information that further illuminates my understanding of the FileMaker paradigm. When I need a break from the process of writing a script, or when I ‘discover’ a function I’ve not used from an answer on the community, I can turn to these pages and explore more about the FileMaker help functions pages. Let’s take a look at how they are set up and let me point out the value in reading these pages on your own.

FileMaker Help Functions Pages

The FileMaker help functions reference set of pages begins here. But I hardly ever start from this location. I usually begin my inquiry from FileMaker itself, and we can do that with the context-sensitive help. If so inclined, you can review functions from the alphabetical list or the category list. The latter is more useful when trying to get a sense of what FileMaker can do with text or numbers.

FileMaker help functions Page Format

Each FileMaker help function’s page follows the same basic format:

  • Name and Purpose (what it returns) of the function
  • The Format
  • Parameters
  • Data Type Returned
  • Originated In
  • Description
  • Notes
  • Examples


This section shows a simple list and description of required parameters. Optional parameters are listed here as well. (I find these optional ones interesting).


Of these sections, I find the “Notes” one incredibly helpful. The text describes quirks or special circumstances or things to be aware of while using the function. Even well-used functions can have some interesting tidbit of information placed in this section.


The Examples are mostly helpful. Often there’s a description of the context (fields, values in fields, tables and relationships). The context can get a bit overwhelming to understand. I tend to just make my own examples as I can in the Data Viewer.

Originated In

The Originated In section is interesting from a historical perspective, and its information would make for quite a few great trivia games. For folks not on the latest version, this is useful. While developing in FileMaker 14, for example, If I’m reviewing the JSON functions, I will see in this section that the functions originated in FileMaker 16. I’m out of luck.

Worth another look

The FileMaker help functions pages have been around for years. They’re updated as functions change or as errors are found. The information found in these pages are worth a look from each and every FileMaker developer. New-to-FileMaker developers can learn the basics of the function. Experienced developers can learn more about the function. As I wrote this, I read that the Substitute function can support up to 999 nested substitutes. I don’t recall knowing that before now.

And since we can get to any function very quickly using the context-sensitive help, it’s worth some time to look and review functions. I review those functions the time just for fun. I also review those functions that are posted in the community as a solution to a specific use case.

It’s worth our time to review these pages once in awhile.

There are a plethora* of places to learn or continue learning FileMaker. A developer, newbie and experienced alike, can read any one of many books. There are courses galore in the web space. There’s the community on which one may ask questions, and of course there’s simply trying, failing, and trying again in the platform itself. But oft overlooked place is FileMaker Help itself. The revamp and much-improved help guide is good for new innovators and those who’ve been working in the platform for a long time.

FileMaker Help

The FileMaker help system has undergone some welcome changes. The help guide for FileMaker Pro Advanced 17 (there is a new help guide for each version release) is much easier to navigate and more pleasing to the eye than versions of old.

The clean, eye-pleasing FileMaker help

The clean, eye-pleasing FileMaker help


Here’s a few highlights from the help guide:

  • The home page contains useful topics defining where to look for answers. Such topics include “Entering Data”, “Finding Data”, “Importing Data” and “Protecting Data”.
  • The home page also contains links to very useful documents. I use the FileMaker Error codes, Product Documentation, and Customer Support links often.
  • There’s a “New Features” category that highlights what’s new in this version of the platform.
  • The search mechanism is thorough. Any word you want to look up having to do with the platform returns many results.
  • The left navigation system is persistent and is easy to navigate.
  • Each page in the guide can be printed in a clean, properly-formatted way.
  • Links abound in the text of the guide, navigating to other places as necessary.
  • The left navigation section shows familiar high-level topics as well. When we click on these, we get a page of text on the topic as well as some subpages on that same idea. In the example, the “Creating Charts from Data” page shows additional pages: About Chart Types, Chart Planning Guides, and others. We can read through an entire concept and easily see each page’s content connection to the whole idea.

The help web pages have become more useful in the past few versions. The organization and links make it very easy to find what you’re looking for.

Accessing FileMaker Help

It is so much easier to get to a specific part of FileMaker’s help. Rather than keeping a browser window and navigating to different areas, we can access what we need from within FileMaker.

This is actually pretty amazing. If I’m working on a chart and I’m in the chart set up, I can press the shortcut key ( Command + / (macOS) ) and in my default browser window up pops the help guide on Charts. I can scan the help document, looking for a particular bit of information, then go right back to work.

The context-sensitive FileMaker help feature is great!

Most of the modal set up windows we work in many times a day contain the context-sensitive help link. Here’s a small list of those that will open up the useful FileMaker help pages.

  • Chart setup dialog
  • Web viewer set up
  • New Layout/Report
  • Script Workspace
  • Portal Setup
  • Manage Database (All the tabs)
  • Manage Security (all the tabs)
  • Preferences

During my testing I discovered that any dialog with the ? Button or the “Learn more. . .” link contains this shortcut. I never knew that.

Curiously, this does not help in some setup dialogs:

  • Button bar
  • Button
  • Calculation Dialog
  • Manage Custom Functions
  • Manage value Lists
  • Edit Relationship

I wonder if these dialogs will eventually get the context sensitive FileMaker help link.

Script Steps & Functions

There are a lot of script steps in the script workspace. There are a lot of functions available in the script dialog. It takes a lot of time to get to know the details about each of these.

As we work to build a script or build a function, we can take advantage of the context-sensitive help to find more details about a step or a function.

Let’s say I need to use the Last () function to set a variable to a certain value. I’m not quite sure how this works, but I saw this offered as an answer on the FileMaker community. In any specific calculation dialog, even the data viewer, I can find that function and review what’s on the bottom-right.

There’s a Description box that describes the basic workings of the function. And there’s a ? button. I can click on that to get more information on this specific function.

The same ideas above apply to script steps. I can learn more about a step by using the context-sensitive help to get directly to that step.

I’m not sure how long this has been around, but I must say I started using this more often and am rather impressed. I can read up on a function or script step while developing in FileMaker. No longer do I have to turn to a book or Google to search for the function. I can get to the help straight from the function itself.

The more you know

I’m taking advantage of this newly-discovered (for me) feature of FileMaker Pro Advanced to do a little reading. When I need a break from the task at hand, or when I want to refresh my memory, or when I am intrigued by someone else’s use of a function and want to learn more, I read the FileMaker help page. There’s a lot of information there and it is useful to read various pages once in awhile.

When I’m on the community people ask how to solve a use case. Invariably I point them to some part of FileMaker help. I’m now using this context-sensitive help feature to get to the specific function or step help page much quicker. I used to have to type “FileMaker 17 Last” in a search engine. Now I don’t have to.


The FileMaker help guide is useful for beginner and veteran alike. There’s plenty to read and learn and remember, and it’s easy to get to those pages that focus on the work you’re doing at the moment. Check it out. Read the FileMaker help.

*plethora: When I was a teacher, the English teacher in my grade taught the students this word. It has stuck with me ever since.

The FileMaker JSON functions we have in FileMaker 16 have changed the development game for many folks. JSONSetElement, JSONGetElmeent, JSONDeleteElement, JSONListValues, JSONListKeys are powerful functions that let us collect data into an object, to parse data from an object, or to edit the object itself. We can even format a JSON object using JSONFormatElements. Since JSON’s purpose is to exchange data, it seems these functions are good enough. We at Geist Interactive have combined these with other FileMaker functions to produce some custom functions (in JSONAdditions.fmp12)  that are useful in many circumstances. Our custom functions actually manipulate the JSON in some way, doing just a bit more than the native functions. In this post, we’ll take a look at a FileMaker filtering JSON function: JSON.FilterByExpression.

You can follow along with this download here.

Simple & straightforward

This is a simple custom function. Its purpose is to return the elements of an array that satisfies an expression. Here’s the syntax:

JSON.FilterByExpression( array ; expression)

You simply pass in it an array and an expression (in quotes), and this custom function returns those elements in the array that satisfy the expression.

The expression is the key. You write an expression that can be used to check a value of a key in each element of the array. Those elements that have have values that meet satisfy the expression are returned.

Let’s apply this custom function to an example, starting with the use case.

Use Case: Given an object returned from the client’s shopping cart website api, chart any number of years’ unit sales. Give the user the ability to choose the start and end year, and display the units sold for that year range on a chart.

Here’s the “sales” array returned from the api and placed into the field: shoppingCart::JSON

"sales" : [
"year" : 2011,
"units" : 43
"year" : 2012,
"units" : 22
"year" : 2013,
"units" : 100
"year" : 2014,
"units" : 2
"year" : 2015,
"units" : 12

JSON.FilterByExpression can easily parse through this array and return those elements that are within the boundary years.

JSON.FilterByExpression ( 
JSONGetElement (shoppingCart::JSON ; "sales")  ;  
"JSONGetElement ($item ; \"year\") ≥ 2012 and JSONGetElement ($item ; \"year\" ) ≤ 2015 

Will return

"year" : 2012,
"units" : 22
"year" : 2013,
"units" : 100
"year" : 2014,
"units" : 2
"year" : 2015,
"units" : 1

The FileMaker filtering JSON custom function is recursive. It will loop over all the elements in an array and construct a new array of those elements that agree with the expression

Express(ion) yourself

The goal of my custom function is to return those elements that have years between 2012 and 2015 inclusively. So that’s how I wrote the expression:

"JSONGetElement ($item ; \"year\") ≥ 2012 and JSONGetElement ($item ; \"year\" ) ≤ 2015"

Notice a few things:

  1. The FileMaker expression must be quoted.
  2. The expression will be applied to each element in the array
  3. The variable $item will contain current item in the array. (Kind of like the current record when looping records.)
  4. I’m using “JSONGetElement()” function to pull the ‘year’ value.
  5. Since the expression is quoted, I’m escaping the ‘year’ key.
  6. I’ve got two parts to my expression in this example. But any expression and any combination of expressions can work.

Here’s what my expression is saying:

For this object in $item, check to see if the value in the key “year” is greater than or equal to 2012 and less than or equal to 2015.

As this FileMaker filtering JSON custom function loops through all the elements in the array, it checks: Does the value in “year” satisfy this expression? If so, add the element to an array.

Finishing the use case

Once I’ve gotten back the array elements that satisfy the expression, I can use another custom function: JSON.GetValuesAtPath (array ; path) to return the “units” values. I’ve done this before in another charting exercise. We will look at this function in a later post.

The full calculation to pull filtered values from an array.

And thus, the chart is born. (Well, there’s a little more to the chart, but you can view that in the sample file).

filemaker json chart

The chart generated using the JSON.FIlterByExpression

The JSON Structure

We got an email of someone struggling with this custom function. It returned a “?”. After examining the person’s data structure, I realized what he gave us wouldn’t work. It looked like this:

{"2012": [
"value": "22"
"2013": [
"value": "100"

The structure, besides being valid though unnecessarily complex, doesn’t contain an array of objects that the custom function JSON.FilterByExpression can loop through. Here the year is the key to a one-element array of one JSON object containing one key/value pair. This is an object. It is not an array, so our custom functions wouldn’t work.

By the way, this makes me wonder: what is the ‘proper’ structure for JSON and data. I will have to explore that.

Our custom functions work with arrays. Specifically, the custom functions loop through the elements of the array and returns a new array or list.

But that’s okay. Our custom functions work with VERY COMMON JSON data structures. Often an api will return arrays within the entire object, just as we see in the working example above. If we can drill down and grab an array from the object, we can use these custom functions.

New tool: FileMaker Filtering JSON

It is wonderful that we now can natively work with FileMaker filtering JSON to gather records into an object, to parse api results, and to manipulate and configure the JSON. We’ve just added a few more we find useful.

Give our JSONAdditions file a try. There’s some useful custom functions that will further your ability to not only generate data into a JSON object, but also to filter, merge and otherwise manipulate an existing object.

If you do adopt these into your own solution, I recommend simply copying / pasting all the custom functions into your file; many of these need other custom functions.

Go forth, now and expand your FileMaker JSON toolset.

If you didn’t download it before, take a look at the sample file. It uses the chart object in FileMaker.

FMPerception is a ghost-hunter, and a successful one at that. The realtime developer intelligence tool can point out all the ‘phantom fields’ on a layout. Let’s take a look at FMPerception’s successful ghost hunt.

What are Phantom Fields?

Unlike the prey of Ghost Hunters, phantom fields are real. They are the fields that are on a table view.

The fields are added in the Modify Table view dialog.

 These fields are not on the layout in layout mode.

They haunt the layout, seen only in Table view. They are phantom fields!

One note: the term Phantom Fields doesn’t come from FileMaker. Instead, the term is how FMPerception defines these. Just so you know.

Giving up the ghost

FMPerception identifies these illusive phantom fields on any layout. 

While looking at a layout, I can view all the layout objects. Each one, if it is on the layout, has a region designation. Phantom fields have the region “Phantom Field”. So if I wish, I can remove those from the layout.

Do I need to get rid of these?

I would say no. These phantom fields are there for a reason. They show themselves only in table view, and if someone has the correct privileges, phantom fields can be added for custom views. With the same privilege set, these phantom fields can be removed from the layout.

FMPerception doesn’t have a report for Phantom Fields like it does for “Unreferenced Objects” or “Broken References”, since phantom fields are not detrimental to a custom app in any way. FMPerception simply identifies them for you on each layout.


So be aware of phantom fields on layouts that allow Table view. And be aware of the identification of these fields in FMPerception. They are of little consequence overall, and they allow quick access for users to create a custom view of the data.