Use and read JSON in Business Central

  • 10 minutes

When you work with web services and APIs that are created as REST services, you'll need to work with JavaScript Object Notation (JSON) data. JSON is a lightweight file format that is used for storing and exchanging data between clients. It's an open standard format that is based on a collection of key/value pairs. JSON uses the JavaScript syntax, but its format is text only. This text can be read and used as a data format by any programming language.

AL in Business Central also has built-in support for working with JSON data. These JSON classes are used for simple data transfer. You can't use the JSON data types as a data type for fields in a table, but you can create variables with the JSON data types.

These classes are an implementation of the System.Json classes from the .NET Framework:

  • JsonToken

  • JsonArray

  • JsonObject

  • JsonValue

All JSON types are reference types, not value types.

The following example shows a JSON sample:

{
   "name": "John",
   "age": 31,
   "address": {
           "city": "New York",
           "country": "US"
   },
   "emails": [ "john@microsoft.com", "john@cronus.com", "john@outlook.com" ]
}

JsonToken

The JsonToken object is a container for any well-formed JSON data. A default JsonToken contains the JSON value of NULL. JsonToken is the base class for the JsonArray, JsonValue, and JsonObject data types.

  • ReadFrom(Text/InStream) - Reads the JSON data from the text or stream into a JsonToken variable.

  • WriteTo(Text/OutStream) - Serializes and writes the JSON data of the JsonToken variable to a given text or stream.

  • SelectToken(JPath, JsonToken) - Selects a JsonToken variable by using a JPath expression.

  • IsArray - Indicates whether a JsonToken represents a JSON array.

  • IsValue - Indicates whether a JsonToken represents a JSON value.

  • IsObject - Indicates whether a JsonToken represents a JSON object.

  • AsArray - Converts the value in a JsonToken to a JsonArray data type.

  • AsValue - Converts the value in a JsonToken to a JsonValue data type.

  • AsObject - Converts the value in a JsonToken to a JsonObject data type.

{
   "company": {
      "employees": [
           { "id": "Marcy", "salary": 8.95 },
           { "id": "John", "salary": 7 },
           { "id": "Diana", "salary": 10.95 }
      ] }
} 

procedure GetSalary(CompanyData: JsonToken; Employee: Text) Salary: Decimal;
var
    JPathExpr: Text;
    SalaryToken: JsonToken;
begin
    JPathExpr := '$.company.employees[?(@.id==''' + Employee + ''')].salary';
    CompanyData.SelectToken(JPathExpr, salaryToken);

    Salary := SalaryToken.AsValue().AsDecimal();
end;

JsonArray

JsonArray is a container for any well-formed JSON array. A default JsonArray contains an empty JSON array. This container works more like a ListOf data type than an array.

Because JsonToken is the base class for JsonArray, you can use some of the following JsonToken methods:

  • ReadFrom(Text/InStream)

  • WriteTo(Text/OutStream)

  • SelectToken(JPath, JsonToken)

  • AsToken (converts the value in a JsonArray to a JsonToken data type)

The JsonArray data type has some helpful methods to work with the items in a JsonArray.

  • Add(Value) - Adds a new value at the end of the JsonArray. This value can be JsonToken, JsonObject, JsonArray, Boolean, Char, Byte, Integer, BigInteger, Decimal, Duration, String, Date, Time, or DateTime.

  • Get(Index, JsonToken) - Retrieves the value at the given index in the JsonArray.

  • IndexOf(Value) - Returns the index position of a certain value.

  • Insert(Index, Value) - Inserts the value at the given index in the array while shifting all the values to the right by one position.

  • RemoveAt(Index) - Removes the token at the given index.

  • Set(Index, Value) - Replaces the value at the given index with a new value.

  • RemoveAll() - Removes all the children of the given array.

  • Count - Gets the number of elements in the JsonArray.

JsonObject

JsonObject is a container for any well-formed JSON object. A default JsonObject contains an empty JSON object. Because JsonToken is the base class for JsonObject, you can use some of the following JsonToken methods:

  • ReadFrom(Text/InStream)

  • WriteTo(Text/OutStream)

  • SelectToken(JPath, JsonToken)

  • AsToken - Converts the value in a JsonObject to a JsonToken data type.

  • Add(Value) - Adds a new property to a JsonObject.

  • Contains(Key) - Verifies if a JsonObject contains a property with a given key.

  • Get(Key, Value) - Retrieves the value of a property with a given key from a JsonObject.

  • Remove(Key) - Removes the property with the given key from the object.

  • Replace(Key, Value) - Replaces the value of the property with the given key with the new value.

  • RemoveAll() - Removes all the properties of the given object.

JsonValue

JsonValue is a container for any well-formed fundamental JSON value. A default JsonValue is set to the JSON value of NULL. Because JsonToken is the base class for JsonValue, you can use some of the JsonToken methods:

  • ReadFrom(Text/InStream)

  • WriteTo(Text/OutStream)

  • SelectToken(JPath, JsonToken)

  • AsToken - Converts the value in a JsonValue to a JsonToken data type.

  • IsNull() - Indicates whether the JsonValue contains the JSON value of NULL.

  • As methods - Convert the value in a JsonValue to a specific data type. Methods includeAsBoolean(), AsByte(), AsChar(), AsInteger(), AsDecimal(), AsCode(), AsText(), AsDate(), and AsDateTime().

  • SetValue(Value) - Sets the contents of the JsonValue variable to the JSON representation of the given value.

  • SetValueToNull() - Sets the contents of the JsonValue variable to the JSON representation of NULL.