FileMaker tips, techniques, and news.
By Jeremiah Kincaid Posted on May 9th, 2017 in FileMaker
FileMaker 16 introduced a set of native JSON (JavaScript Object Notation) functions that, along with native cURL options, allow developers to interact with REST APIs without the need for a plugin. And as an added bonus, the JSON functions can be used for multiple parameter passing in scripts, giving developers a much-welcomed standard that will likely displace the current assortment of custom functions throughout the FileMaker community.
Let's take a look at how to use the new JSON functions:
There are 6 JSON functions available in FileMaker 16:
Understanding these three are critical to a happy life with JSON, as they are needed for every function. The real power is in paths, but to understand paths, you must know how to use keys and indexes.
Keys and indexes are pretty much what they say on the tin: supply a JSON function a key and it'll return the element associated with the key. And supply a function an array index, and it'll return the element associated with that index.
Let's check out a couple examples. Assuming we start with this contact JSON document in a $json variable
{ "firstName" : "John", "lastName" : "Doe", "address" : [ { "type" : "Billing", "city" : "Indianapolis", "state" : "IN" }, { "type" : "Shipping", "city" : "Cincinnati", "state" : "OH" } ] }
to get the last name of the contact, we would use the function JSONGetElement( ) with the lastName key
JSONGetElement( $json ; "lastName" )
which gives us
Doe
For array indexes, supply the array's key, and then the index of the array element you want in brackets. In our example JSON, to get the contact's shipping address, we would use JSONGetElement with the address key and an index of 1 (indexes start at 0, a deviation from most of FileMaker, but consistent with the JSON standard):
JSONGetElement( $json ; "address[1]" )
which results in
{ "type" : "Shipping", "city" : "Cincinnati", "state" : "OH" }
Now that we've gotten introduced to keys and indexes, let's take a look at paths. Paths are an ordered list of keys and indexes separated by dots that tell FileMaker the exact element you want in a JSON document, which is necessary if there are multiple elements in the same document with the same key, or if you want an element inside an array. Paths start at the top of the document and end at the element you want.
Let's say we wanted to get the city of the contact's shipping address. To do that all in one function call, we would need to use the path "address[1].city". Address is the first element from the top of the doc that leads us toward the city we're looking for, the shipping address is in index 1 of the address array, and we want the city element of that address object. In FileMaker speak, the function call is
JSONGetElement( $json ; "address[1].city" )
which gives us
Cincinnati
You only need one function to create or modify a JSON document: JSONSetElement( ). And now that we have some familiarity with keys, indexes and paths, the JSONSetElement( ) function will make a lot more sense. Let's see it in action.
To create the example contact JSON document using JSONSetElement( ), we'll enlist the use of paths that tell FileMaker at which part of the JSON document to create the new elements, along with the bracket notation to allow us to perform multiple JSONSetElement()s in one call, just like the Substitute( ) function:
JSONSetElement( "{}" ; [ "firstName" ; "John" ; JSONString ] ; [ "lastName" ; "Doe" ; JSONString ] ; [ "address[0].type" ; "Billing" ; JSONString ] ; [ "address[0].city" ; "Indianapolis" ; JSONString ] ; [ "address[0].state" ; "IN" ; JSONString ] ; [ "address[1].type" ; "Shipping" ; JSONString ] ; [ "address[1].city" ; "Cincinnati" ; JSONString ] ; [ "address[1].state" ; "OH" ; JSONString ] )
Contrast that to this, the non-bracketed version
JSONSetElement( JSONSetElement( JSONSetElement( JSONSetElement( JSONSetElement( JSONSetElement( JSONSetElement( JSONSetElement( "{}" ; "firstName" ; "John" ; JSONString ) ; "lastName" ; "Doe" ; JSONString ) ; "address[0].type" ; "Billing" ; JSONString ) ; "address[0].city" ; "Indianapolis" ; JSONString ) ; "address[0].state" ; "IN" ; JSONString ) ; "address[1].type" ; "Shipping" ; JSONString ) ; "address[1].city" ; "Cincinnati" ; JSONString ) ; "address[1].state" ; "OH" ; JSONString )
The bracket notation is much easier to read. And faster to write. A win-win.
JSONGetElement( "" ; "lastName" )Gives back error
? * Line 1, Column 1 Syntax error: value, object or array expected. * Line 1, Column 1 A valid JSON document must be either an array or an object value.Instead, pass an empty object {} or an empty array [].
ValueCount( JSONListKeys( $json ; "address" ) )gives our answer
2
The crux of multiple parameter passing in scripts is being able to create key-value pairs, which is JSON's bread and butter. No more need for dictionary or associative list custom functions - all parameter passing can now be done with the JSON functions. We updated our free template, FM Quickstart, to use JSON for parameter passing, instead of our alist custom functions. We hope the rest of the community embraces JSON as a standard for parameters. It'll make working in, reading and understanding other developers' code much easier.
With the advent of JSON functions, FileMaker developers now have the ability to natively create and parse JSON for REST APIs, multiple script parameter passing, and more. Check out our other articles on FileMaker 16 for more information about all the new and exciting capabilities we have at our disposal with this release of FileMaker. Please contact us if you would like help taking advantage of FileMaker's new JSON functions.
Did you know we are an authorized reseller for Claris FileMaker Licensing?
Contact us to discuss upgrading your Claris FileMaker software.
Jeremiah is a Certified Salesforce Architect and Consultant who has been with DB Services since 2007. A Purdue University graduate, Jeremiah earned dual bachelors in Chemistry and Philosophy. His educational background and natural smarts gives him the ability to be successful both in the trenches of scripts as well as in collaboration with co-workers and clients. A rarity, indeed.