FileMaker tips, techniques, and news.

By Jeremiah Kincaid  Posted on  May 9th, 2017  in  FileMaker

FileMaker JSON Functions

FileMaker 16 has 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:

Meet the Functions

There are 6 JSON functions available in FileMaker 16:

  • JSONSetElement - Adds or modifies an element in a JSON document at the supplied key, index or path. The new value, and the value's data type, are passed as the 3rd and 4th arguments.
  • JSONDeleteElement - Deletes an element at the supplied key, index, or path.
  • JSONGetElement - Returns an element at the supplied key, index, or path.
  • JSONListKeys - Lists all the keys or array indexes at the supplied key, index, or path.
  • JSONListValues - Lists all the values at the supplied key, index, or path.
  • JSONFormatElements - Formats a JSON document so it's easier to read (i.e. it separates key-value pairs onto different lines, and adds indentation based on the nesting structure). Very useful when you are troubleshooting JSON.

Keys, Indexes, and Paths (Aka Parsing JSON)

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 & 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"
}

Paths

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

Creating JSON

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.

Some Items to Note about the Functions

  • Avoid null JSON documents. Avoid passing null JSON documents to the parsing functions - the functions will return an error. For example

    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 [].
  • Use explicit data types in JSONSetElement( ). While this is personal preference, you should explicitly state the data type in JSONSetElement( ) calls. Not only does this ensure FileMaker doesn't accidentally convert values to wrong data types, but explicit types make code easier to read than blank arguments.
  • Use JSONListKeys() to get an array's size. While there's no function to directly get an array's size, you can do this using JSONListKeys() in tandem with ValueCount( ). For example, to get the count of addresses for our example contact JSON, doing this
    ValueCount( JSONListKeys( $json ; "address" ) )
    	
    gives our answer
    2
    	

New Standard for Multiple Script Parameters

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.

Conclusion

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.

Did you know we are an authorized reseller for FileMaker Licensing?
Contact us to discuss upgrading your FileMaker software.

Jeremiah Kincaid thumbnail
Jeremiah Kincaid

Jeremiah is a Certified FileMaker and Salesforce Developer who has been with DB Services since 2007. A Purdue University graduate, Jeremiah earned dual bachelors in Chemistry and Philosophy while simultaneously learning FileMaker. 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.

FileMaker 18 Certified Developer
FileMaker 17 Certified Developer
FileMaker 16 Certified Developer
FileMaker 15 Certified Developer
FileMaker 14 Certified Developer
FileMaker 13 Certified Developer
FileMaker 12 Certified Developer
FileMaker 11 Certified Developer
"We were actually able to add more features than we thought would be possible within our budget. We always experienced a ‘can do’ attitude and DB Services was incredibly patient and easy to work with."
Courtney Hartman
Art Director
"The new FileMaker custom website interface is very user-friendly and easy to follow for our clients. In addition, it is much faster than the old Instant Web Publishing (IWP) interface. Thank you and all the others who have helped us out at DB Services. I am very grateful for the excellent service you provide us. Its nice to know we can call you for help if we have an issue."
Wayne Capek
President
"We needed a solution that would simplify the administration of our responsibilities under our contract with the State of Indiana. We have seen a dramatic increase across the state in the number of potential foster and adoptive parents that have begun the preparation and training process. This increase has resulted in a significant opportunity for children available for adoption. That’s a big win for everyone! And it’s all because we can refer potential parents to the proper state contacts efficiently and quickly."
Chris Morrison
Executive Director
"Thank you for all of your expertise and valuable help. I am so grateful to have found DB Services."
Linda Findlay
Owner
"Thank you for our new database system. We transitioned from a carbon copy paper based system to a digital database. The software has saved us time and money. We used to archive all our jobs in cabinets, now we can look up a job in seconds from anywhere. The software allows us to easily email estimates to our customers in pdf format. In a year there was a return on investment just from eliminating the purchasing of our carbon forms."
Todd Cartmel
Owner
"The new system allows us to create and track jobs for customers along with inventory, something we had been doing with separate word and spreadsheet files. Because it’s now so intuitive, new staff members are able to begin using the database immediately without our usual training session and ‘cheat sheets’ for getting around within the file."
Tom Andrews
President