Last year I developed an integration to an external REST API from Business Central. One of the things that I had to learn is how to deal with JSON. We now have a bunch of different JSON data types, and if you’re just getting into them, they are hard to keep apart. With this post, I’ll try to explain as easy as I can make it, how to create a JSON object in AL.
JSON Basics
First, of course, the basics.
- JSON is short for ‘JavaScript Object Notation’, follow this link to read the actual standards but if you’re new to this don’t though, it will only confuse you
- It’s kind of like XML in concept but much easier to read. No attributes, no formatting rules, just a collection of key/value pairs
- The equivalent of an ‘XML document’ is called a ‘JSON Object’. The start and end of these JSON objects are marked by curly braces (these {}).
- Keys and values are always between double quotes (unless they are in non-text data types, but you can always put values in double quotes), separated by a colon. Multiple key/value pairs are separated by commas. This is a very simple JSON object with some key/value pairs:
{
"A Key": "Example One",
"Another Key": "Another Value",
"Number Value": 42,
"Boolean Value": false
}
- Nesting is done by adding a new JSON object as a value, like this:
{
"A Key": "Example Two",
"Nested thing": {
"First nested Key": "nested value",
"Second nested key": "some other value"
}
}
- A list of JSON objects is called a ‘JSON Array’. The only restriction here is that each of the objects in an array must be structured the same, otherwise it would not be an array. The start and end of a JSON array is marked by square brackets. Each object has its own start/end curlies, and they are separated by commas. Here’s a simple example:
{
"A Key": "Example Three",
"List of Things": [
{
"name": "thing 1",
"age": 10
},
{
"name": "thing 2",
"age": 12
}
]
}
Note that the objects inside the array are identical in structure. This is really it, you should now be able to decipher any JSON response from any web service.
JSON Data Types in AL
In AL, there are 4 different JSON data types. All of these data types are .NET types that are wrapped in AL data types. You don’t have to worry about constructing these variables, they take care of themselves. All you have to do is make sure that you start with a fresh one, so pay attention to the scope of your variables. If you are not sure about that, use the Clear keyword to empty it out.
- JsonObject – this data type represents an actual JSON object. It has properties and methods, and you use those to build the object as shown in the code examples below
- JsonArray – this data type is also an object with properties and methods, and it contains the stuff that is between the square brackets
- JsonValue – this represents a single value of a simple data type like a Text, an Integer, or a Boolean
- JsonToken – in the JSON world, the ‘Token’ is similar to a Variant, and it can be either one of the other three Json data types. If you are not sure about the content of a JSON element, you can always use a Token as a data type
Show Me The Code!
When I started this section I was going down a rabbit hole of long sentences and complicated explanations. As I was reading what I wrote I realized that describing these things actually was not making any sense at all. Let me just give you the code, and if you have any questions about this please leave a comment below.
Each example refers to the JSON examples in the ‘JSON Basics’ section above.
Example One
The first example is very straight forward. This object only has simple key/value pairs, so we can simply add those to the object, like this:
procedure ExampleOne()
var
MyJobject: JsonObject;
begin
MyJobject.Add('A Key', 'Example One');
MyJobject.Add('Another Key', 'Another Value');
MyJobject.Add('Number Value', 42);
MyJobject.Add('Boolean Value', false);
end;
Example Two
The second example has another JSON object as one of its values. The ‘Add’ method of the JsonObject data type takes a string as the Key name, and a JsonToken as the value parameter. In the first sample those were simple datatypes, and for this second sample we’re going to create another object to use as the value parameter, like this:
procedure ExampleTwo()
var
MyJobject: JsonObject;
NestedJObject: JsonObject;
begin
MyJobject.Add('A Key', 'Example Two');
NestedJObject.Add('First Nested Key', 'nested value');
NestedJObject.Add('Second Nested Key', 'some other value');
MyJobject.Add('Nested thing', NestedJObject);
end;
Example Three
The final example includes an array of objects, so we’ll build those one step at a time. Everything just coded in there, I hope you see how the array objects should be refactored into a re-usable function.
procedure ExampleThree()
var
MyJobject: JsonObject;
ThingJObject: JsonObject;
MyJArray: JsonArray;
begin
MyJobject.Add('A Key', 'Example Three');
Clear(ThingJObject);
ThingJObject.Add('name', 'thing 1');
ThingJObject.Add('age', 10);
MyJArray.Add(ThingJObject);
Clear(ThingJObject);
ThingJObject.Add('name', 'thing 2');
ThingJObject.Add('age', 12);
MyJArray.Add(ThingJObject);
MyJobject.Add('List of Things', MyJArray);
end;
What about JsonToken?
We did not use a variable of type JsonToken directly, because when we are creating a JSON Object we already know what we have. Indirectly though, we definitely ARE using a Token. The ‘Add’ method of both the JsonObject and the JsonArray data types use a Token as the value parameter. Since the Token can be any simple type or any other Json type, you can simply throw any of those in and it knows what to do with it.
The JsonToken type will come in very useful when you start processing incoming JSON objects, and you need to make sure you correctly convert values into compatile data types in AL.
What’s Next?
These are just some very simple examples of how to build a JSON object, but this is really all the logic you’ll ever need to create your own. The JsonObject will take care of the curlies and the commas, the JsonArray will take care of the square brackets and all the other stuff. The only slightly complex thing you’ll ever need to do beyond this is to now take the JsonObject and set it as the body of an HttpRequest.
Let me know in the comments if this is helpful. There are other super useful posts about this topic, but I wanted to explain this in my own words. I will also write one how to read an incoming JSON object, and at some point I’ll share some helper logic that I’ve created to help take care of conversions and such.
Thank you so much. All 3 examples solved my challenge.
You’re welcome Jesper, thanks for the note