• Who: Anyone who uses checkbox sets with the Data API.
  • What: How to Format JSON key/value pairs for a Checkbox Set.
  • With: FileMaker 17+
  • Why: Checkbox sets are common and useful tools in forms when sending data to the Data API.

 

Problem

As of this writing, there is no documentation on how to send data to a checkbox field via the Data API for record creation or editing.  After a significant attempt to find any examples or documentation, I realized that a clue might be found by getting the data from an existing record with a checkbox set using the http GET method.

 

Solution

The record retrieved was a single key/value pair with JSON carriage returns between each value like this:

{ “fieldData“:
{ “myCheckBoxField“: “Check1\rCheck2\rCheck3“}
}

It turns out that by simply sending checkbox set values via an http POST method with this same format, the record is created or edited in FileMaker with the matching checkbox values!  In other words, all you have to do to create or edit a checkbox set in FileMaker is use a key/value pair where the values for the checkbox set are simply separated by the JSON special character for carriage returns: \r

In the JSON example above showing the key/value pair for the key: myCheckBoxField, you can simply simply send the data in the exact same format: “Check1\rCheck2\rCheck3”.  Whatever values are listed with carriage returns will populate or edit the checkbox field in the FileMaker record.  For an edit, even if a different set of values already existed, this method overwrites whatever the old values were and just uses the new values you send.

Note that if one of the values you send doesn’t EXACTLY match with the values in the checkbox valuelist set  in FileMaker, that value won’t show up as a checked box.  However, if you check the record with the Data Viewer, you will see that the value you sent still exists as part of the data in that field, it just doesn’t show as a checked box (because there wasn’t a box representing that EXACT value to check).

For example, if you send the JSON in the example above, but misspell “Chcek3”,  “Chcek3” will still be set as part of the value in that field, but it won’t cause the “Check3” box to actually be marked.

 

How to Create the Value String

Some of you might be wondering. “Ok, that’s nice, but how do I create the JSON value like that with those carriage returns?” Well, since there are dozens of potential languages you might be using on your front end we can’t provide examples for all, but the general idea is to simply concatenate them all into a string.  If you’re using a form on the web, you would first have to collect those values from the form, then concatenate them into a variable which you would then assign to your JSON key/value pair.  For example, if you’re using Javascript you might do something like this:

let check1 = “Hello”
let check2 = “world!”
let bothChecks = check1 + “\r” + check2

The above example would yield: “Hello\rworld!” where FileMaker would receive 2 values for a checkbox set.  The whole JSON example would look like:

{ “fieldData“:
{ “myCheckBoxField“: “Hello\rworld!“}
}

 

Finally, it’s also important to note that there are special characters in JSON that are reserved and must be properly escaped to be used:

  • Backspace is replaced with \b
  • Form feed is replaced with \f
  • Newline is replaced with \n
  • Carriage return is replaced with \r
  • Tab is replaced with \t
  • Quote is replaced with \”
  • Backslash is replaced with \\

On my journey to figure out how to format the JSON for checkbox sets, I also discovered that there are quite a few online tools to automatically format your JSON!  If you’re using Javascript and you use the JSON.stringify() method to send your JSON to the Data API, one of these JSON formatters can really help!  Try one for yourself! Online JSON Escape Formatter

Hope that helps!