![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/FM16JSON-1024x512.jpg\")
<\/p>\nFileMaker\u2122 16 introduces native JSON parsing which may finally give us a common language for passing multiple script parameters. This should\u00a0make sharing scripts\u00a0a lot easier. And while unpacking (reading) JSON script parameters is pretty simple, there are a few tricks to passing (writing) JSON using FileMaker’s new functions.<\/p>\n
<\/p>\n
The new release of FileMaker 16 includes\u00a0built-in functions for reading and writing JSON<\/a>: a lightweight data-interchange format widely used to pass data around between web apps. This is why it was included in FileMaker 16: to complement the enhanced cURL support, but we can use it outside of a web context\u00a0to make script parameters much\u00a0more reliable.<\/p>\n (If you’re just looking for the example file, here it is:\u00a0JSONScriptParameters.fmp12<\/a>)<\/em><\/p>\n While I\u2019m relatively new to FileMaker, I have quite a bit of experience with JSON. And, honestly, I found FileMaker\u2019s JSON implementation to be a little quirky\/unique. I would venture to say that I even disagree with how the very important JSONGetElement function is implemented. This brings me to the first, and most surprising, thing about FileMaker\u2019s JSON implementation:<\/p>\n \\ Weird, but we can work with it. More on this later =)<\/p>\n We\u2019re going to be exploring whether it can be beneficial to pass multiple script parameters between FileMaker scripts using the JSON as the parameter format. To review, passing single parameters between scripts is built-in to FileMaker, but once you need to pass more than one parameter, you need to come up with some kind of grammar in order to tell one parameter from another. And it would be good if your grammar understood blank parameters and didn’t freak out when your parameter contained something unexpected like a carriage return.<\/p>\n Currently, in order to pass multiple parameters\u00a0from one FileMaker script to another, you can:<\/p>\n (Spolier: Yes) But there are a few things to keep in mind and they’re mostly around writing JSON (as opposed to reading it). I’ve put together an example file showing how I like to write and read JSON in this context. You don’t need the file to follow along with this article, but there are some scripts you may want to copy from it when you’re parsing your own JSON. Download the example file\u00a0here: JSONScriptParameters.fmp12<\/a><\/p>\n First, let\u2019s look at the method for\u00a0writing a JSON string with multiple parameters. The following statement will create a JSON object with 3 name\/value pairs (three script parameters) in it:<\/p>\n That would create a string\u00a0which looks like this:<\/p>\n And when that’s used as a script parameter, we can get the individual parameter we’re looking for like this:<\/p>\n Which returns: “Dog”<\/p>\n If you want to play with JSON like this, I encourage you to put it in the data viewer so that you can change\u00a0it more easily than you can in scripts:<\/p>\n There are a few things to note about this simple example:<\/p>\n <\/i> Despite the order in which you pass your named elements, they will be in alphabetical order in your JSON.<\/strong><\/p>\n and<\/p>\n The names are case sensitive, so JSONGetElement ( Get ( ScriptParameter )\u00a0; “animal” ) wouldn’t work in this example.<\/strong><\/p>\n Notice the 3rd parameter of each object specifying the data type (JSONString, JSONNumber, etc.). You either need to specify the type of each value that you\u2019re passing, or let the JSON parser do that for you by leaving the third parameter blank (using “”) instead of something like JSONString. At this time, there\u2019s no auto-complete for these values, so you\u2019ll need to remember them.<\/p>\n You can find the 7 types of JSON values in the documentation<\/a>, but here they are for reference…<\/p>\n The value included in the JSON is always included in quotes, even if you passed in a number. This is the same as applying FileMaker’s GetAsText() function to the value before passing it in.<\/p>\n Example input: \u201ctext1\u201d The value included in the JSON\u00a0is included without quotes. This is the same as applying FileMaker’s GetAsNumber() function to the value before passing it in and will transform dates\u00a0to numbers as shown in the third\u00a0example.<\/p>\n Example input:\u00a012345.67 <\/i> Note that blank values passed in using JSONNumber will be sent as 0: use JSONNull if you want to pass a blank value.<\/p>\n Nest one JSON object as a member in another object.<\/p>\n Example input: “{ \\”a\\” : 11 }” A collection of delimited values tied to one name within\u00a0your JSON. Some people might\u00a0pass multiple values like this as return delimited text using JSONString, but using JSONArray\u00a0lets you address an individual member of the array\u00a0by position\u00a0instead of using GetValue()<\/p>\n Example input: an array of objects. The objects can be any one of the 7 JSON objects. This can be used for a list of numbers \u201c[1,2,3,4,5]\u201d or text\u201c[\\\u201cstring1\\\u201d,\\\u201dstring2\\\u201d,\\\u201dstring3\\\u201d,\\\u201dstring4\\\u201d]\u201d or even a list of nested JSON strings. Example use: First, set the array to a local variable from the parameters: Set Variable [ $array : JSONGetElement ( Get(ScriptParameter) ; \u201carray\u201d] ]<\/p>\n Next, retrieve the first value from the array and set as another local variable: Set Variable [ $array1 : JSONGetElement ( $array ; 0)]<\/p>\n <\/i> Keep in mind that the way FileMaker decided to implement this, with JSON arrays and objects, the first item is at the index 0, not 1. So the first item will be item 0, then 1, 2, 3 and so on. This can be confusing for FileMaker users since with functions such as GetValue, the first item in the array is 1.<\/p>\n True, true, “true”, 1, and any text containing a 1 are all equivalent to true. False, \u201cFalse\u201d, “True”, and 0 are equivalent to false. In reality, anything that does not match the 55\u00a0true options, such as \u201csomeText\u201d, will be evaluated as false.<\/p>\n Example input: True It would evaluate to false, since the value is actually 1, not \u201ctrue\u201d.<\/p>\n This creates a named, empty member, regardless of what you pass in.<\/p>\n Example input: \u201ctext1\u201d The same as leaving the third parameter blank (using “”). The value you pass in is run by the JSON parser and it does its best guess as to data type. This actually works pretty well for text and numbers and returns blank for blank fields. It even treats arrays like arrays if they look like arrays =). But as you’l seen in our third, fourth, and fifth example below, it can make some strange assumptions when you mix text and numbers.<\/p>\n Example input: \u201ctext1\u201d <\/i> JSONRaw can make some strange assumptions about values that mix text and numbers.<\/p>\n As you can see, those not familiar with JSON may find this structure a bit difficult to write and may dismiss JSON as an option at this point.<\/p>\n One could make this easier to write by creating\u00a0FileMaker custom function to help with JSON\u00a0creation. Custom functions can be used to make common tasks easier and, in this case, they could obviate the need for remembering the third parameter by having it in the name, like “JSONSetNumber”. I find the third parameters pretty easy to remember, but regardless of how you write your JSON, the\u00a0biggest benefit to passing parameters\u00a0in JSON is that no matter which method you use to construct it, the string that is passed to the receiving script is always going to adhere to a standardized structure.<\/p>\n Once we\u2019ve passed our JSON array to our script in a parameter, this is where the benefits come in. Next, you\u2019ll want to retrieve your\u00a0values\u00a0from the JSON string. You have a few options with this:<\/p>\n 1.<\/strong> Explode each of the values\u00a0in the array to a local variable using a loop or custom function.<\/p>\n 2.<\/strong> Set each parameter needed to a local variable in its own JSONGetElement line at the top of your script.<\/p>\n 3.<\/strong> Extract only the parameters you need from the script parameter\u00a0as you use them.<\/p>\n With option two, possibly the most useful, you can set a single parameter from the input to a local variable using the following line:<\/p>\n This can be repeated for each parameter\u00a0your script requires. The advantage to this method is that it lets another developer\u00a0know which variables they have to work with just by reading the top of your script. Here’s just such a script from our example file:<\/p>\nNo matter what data type you pass into your JSON parameter, the result will always be returned as text by FileMaker’s JSONGetElement function.<\/s> Note. As of 16.0.2, JSONGetElement now correctly returns Numbers and Booleans. It no longer always returns Text =)<\/strong><\/p>\n\n
Is formatting script parameters as JSON an improvement?<\/h2>\n
Writing JSON in FileMaker 16<\/h2>\n
JSONSetElement ( \"{}\";\n [\"Animal\"; SomeTable::Animal ; JSONString];\n [\"Age\"; SomeTable::Age ; JSONNumber];\n [\"Vaccinated\"; SomeTable::Vaccinated ; JSONBoolean]\n)<\/pre>\n{\"Age\":12,\"Animal\":\"Dog\",\"Vaccinated\":true}<\/pre>\nJSONGetElement ( Get ( ScriptParameter )\u00a0; \"Animal\" )<\/pre>\n
![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jasonsimple-1024x642.png\")
<\/a><\/p>\nJSONString<\/h4>\n
\nAdded to the JSON as: \u201ctext1\u201d
\nJSONGetElement result: \u201ctext1\u201d<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonstring-1024x648.png\")
<\/a>![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonstring2-1024x642.png\")
<\/a>JSONNumber<\/h4>\n
\nAdded to the JSON as:\u00a012345.67
\nJSONGetElement result: 12345.67\u00a0(looks like a number, but remember: JSONGetElement always returns text, as shown in the second\u00a0example)<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonnumber1-1024x642.png\")
<\/a>![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonnumber2-1024x642.png\")
<\/a>![\"JSONNumber](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonnumber3-1024x642.png\")
<\/a>![\"FMP](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonnumber4-1024x642.png\")
<\/a>JSONObject<\/h4>\n
\nAdded to the JSON as: \u201c{“a”:11}\u201d
\nJSONGetElement result: \u201c{“a”:11}\u201d<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonobject-1024x642.png\")
<\/a>JSONArray<\/h4>\n
\nAdded to the JSON as: \u201c[1,2,3,4,5]\u201d
\nJSONGetElement result: a text value containing an array of objects that must be extracted using JSONGetElement<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonarray-1024x642.png\")
<\/a>![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonaray2-1024x642.png\")
<\/a>JSONBoolean<\/h4>\n
\nAdded to the JSON as: true (note the lack of quotes)
\nJSONGetElement result: 1 Interestingly, no matter how you entered the boolean, the returned value will always be 1 or 0. If you pass the parameter \u201cVaccinated\u201d as \u201ctrue\u201d and use the following if statement to read it:<\/p>\nJSONGetElement ( Get ( ScriptParameter) ; \"Vaccinated\" ) = \"true\"<\/pre>\n
![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonboolean1-1024x642.png\")
<\/a>![\"FM](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonboolean2-1024x642.png\")
<\/a>![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonboolean3-1024x642.png\")
<\/a>JSONNull<\/h4>\n
\nAdded to the JSON as: \u201c\u201d
\nJSONGetElement result: \u201c\u201d<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonnull1-1024x642.png\")
<\/a>JSONRaw<\/h4>\n
\nAdded to the JSON as: \u201ctext1\u201d
\nJSONGetElement result: \u201ctext1\u201d<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonraw1-1024x642.png\")
<\/a>![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonraw2-1024x642.png\")
<\/a>![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonraw3-1024x642.png\")
<\/a>![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonraw4-1024x642.png\")
<\/a>![\"\"](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/jsonraw5-1-1024x642.png\")
<\/a>Reading JSON – unpacking your script parameters<\/h2>\n
\nFirst, you\u2019ll want your script to verify the received parameter is valid JSON:<\/p>\n![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/script.png\")
<\/a><\/p>\nSet Variable [$sc_Animal; JSONGetElement ( Get(ScriptParameter); \"Animal\")]<\/pre>\n
![\"FileMaker](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/script2-1024x847.png\")
<\/a><\/p>\n![\"JSON](\"https:\/\/archive.seedcode.com\/wp-content\/uploads\/2017\/05\/GetValuesscript-1024x745.png\")
<\/a><\/p>\n