In our previous post, we explored how to parse JSON using AL’s basic objects. That approach works for simple data structures, but real-world integrations often demand more flexibility. Enter Codeunit 5459 – JSON Management, a powerful toolset for reading, writing, and converting JSON in a clean, reusable way.

If you missed our earlier guide, check out [How to Work with JSON in Business Central’s AL Code]. This article builds on that foundation to show how JSON Management simplifies complex data handling and supports SaaS-safe operations for Business Central developers.

JsonMgt: Codeunit "JSON Management";

Codeunit 5459 – JSON Management is one of the most comprehensive helper units in Business Central. To make navigation easier, I’ve grouped its procedures into Read, Write, and Convert categories. Each group provides a flexible foundation for handling JSON in a clean, reusable way, whether you’re extracting values, building payloads, or converting data between formats.

Before diving in, note that this codeunit includes several On‑Prem‑only procedures. If you’re working in a SaaS environment, not all methods will be available. The examples and documentation here focus exclusively on SaaS‑safe operations, ensuring compatibility across cloud deployments.

Read Operations

GetObjectFromCollectionByIndex(var Object: Text; Index: Integer): Boolean

Parameters: var Object: Text, Index: Integer
Returns: Boolean
Description: Retrieves a JSON object from the current collection by its index and returns it as text.

GetJObjectFromCollectionByIndex(var JObject: DotNet JObject; Index: Integer): Boolean

Parameters: var JObject: DotNet JObject, Index: Integer
Returns: Boolean
Description: Retrieves a JSON object from the collection at a specific position as a JObject.

GetPropertyValueByName(propertyName: Text; var value: Variant): Boolean

Parameters: propertyName: Text, var value: Variant
Returns: Boolean
Description: Reads a named property from the currently loaded JSON object.

GetPropertyValueFromJObjectByPath(JObject: DotNet JObject; fullyQualifiedPropertyName: Text; var value: Variant): Boolean

Parameters: JObject: DotNet JObject, fullyQualifiedPropertyName: Text, var value: Variant
Returns: Boolean
Description: Reads a nested property using a dot-separated path such as Parent.Child.Property.

GetStringPropertyValueByName(propertyName: Text; var value: Text): Boolean

Parameters: propertyName: Text, var value: Text
Returns: Boolean
Description: Reads a property from the current object and returns it as text.

GetArrayPropertyValueAsStringByName(propertyName: Text; var value: Text): Boolean

Parameters: propertyName: Text, var value: Text
Returns: Boolean
Description: Reads an array property and returns its JSON content as text.

GetValue(Path: Text): Text

Parameters: Path: Text
Returns: Text
Description: Retrieves a value from the current JSON object using a path expression.

GetValueAndSetToRecFieldNo(RecordRef: RecordRef; PropertyPath: Text; FieldNo: Integer): Boolean

Parameters: RecordRef: RecordRef, PropertyPath: Text, FieldNo: Integer
Returns: Boolean
Description: Reads a JSON property and writes its value directly into a record field.

HasValue(Name: Text; Value: Text): Boolean

Parameters: Name: Text, Value: Text
Returns: Boolean
Description: Checks whether a property exists and begins with the supplied value.

ReadProperties(): Boolean

Parameters: None
Returns: Boolean
Description: Prepares the current JSON object for property iteration.

GetNextProperty(var Name: Text; var Value: Text): Boolean

Parameters: var Name: Text, var Value: Text
Returns: Boolean
Description: Returns the next property from the current JSON object during iteration.

GetCount(): Integer

Parameters: None
Returns: Integer
Description: Returns the number of properties in the current JSON object.

GetCollectionCount(): Integer

Parameters: None
Returns: Integer
Description: Returns the number of items in the current JSON array.

Write Operations

InitializeCollection(JSONString: Text)

Parameters: JSONString: Text
Returns: None
Description: Loads a JSON string into the internal collection state.

InitializeEmptyCollection()

Parameters: None
Returns: None
Description: Creates a new empty JSON array.

InitializeObject(JSONString: Text)

Parameters: JSONString: Text
Returns: None
Description: Loads a JSON string into the internal object state.

InitializeEmptyObject()

Parameters: None
Returns: None
Description: Creates a new empty JSON object.

InitializeFromString(JSONString: Text): Boolean

Parameters: JSONString: Text
Returns: Boolean
Description: Parses a JSON string into the current object state and reports whether the parse succeeded.

SetValue(Path: Text; Value: Variant)

Parameters: Path: Text, Value: Variant
Returns: None
Description: Sets a value at a specific JSON path within the current object.

AddArrayValue(Value: Variant)

Parameters: Value: Variant
Returns: None
Description: Appends a value to the current JSON array.

AddJson(Path: Text; JsonString: Text)

Parameters: Path: Text, JsonString: Text
Returns: None
Description: Parses a JSON object from text and inserts it into the current JSON structure.

AddJsonArray(Path: Text; JsonArrayString: Text)

Parameters: Path: Text, JsonArrayString: Text
Returns: None
Description: Parses a JSON array from text and inserts it into the current JSON structure.

SetJsonWebResponseError(var JsonString: Text; code: Text; name: Text; description: Text)

Parameters: var JsonString: Text, code: Text, name: Text, description: Text
Returns: None
Description: Adds standard error fields to a JSON response payload.

WriteCollectionToString(): Text

Parameters: None
Returns: Text
Description: Serializes the current internal array back to a JSON string.

WriteObjectToString(): Text

Parameters: None
Returns: Text
Description: Serializes the current internal object back to a JSON string.

Convert Operations

XMLTextToJSONText(Xml: Text) Json: Text

Parameters: Xml: Text
Returns: Json: Text
Description: Converts XML content into a JSON string for easier manipulation in code.

JSONTextToXMLText(Json: Text; DocumentElementName: Text) Xml: Text

Parameters: Json: Text, DocumentElementName: Text
Returns: Xml: Text
Description: Converts JSON content into XML text using the supplied document element name.

FormatDecimalToJSONProperty(Value: Decimal; PropertyName: Text): Text

Parameters: Value: Decimal, PropertyName: Text
Returns: Text
Description: Formats a decimal value as a single JSON property string.

The key thing to know about using this code unit is the persistence of data inside the code unit. Unlike the JSONObject where we need to manage the JSONObject Variable in our procedure, the Code Unit holds the JSON so we can manipulate it procedurally with just the Code Unit variable. This is very convenient as we keep the JSON and the tools in the same variable.

codeunit 50100 "Demo JSON Mgmt"
{
    procedure DemoJSONHandling()
    var
        JsonMgt: Codeunit "JSON Management";
        JsonText: Text;
        CustomerName: Text;
        ResultJson: Text;
    begin
        // 1. Load JSON into the codeunit
        JsonText := '{"customer":{"name":"Aardvark","id":"C001"}}';
        JsonMgt.InitializeFromString(JsonText);

        // 2. Read a value from the JSON
        CustomerName := JsonMgt.GetValue('customer.name');
        Message('Customer name: %1', CustomerName);

        // 3. Add or update values
        JsonMgt.SetValue('customer.status', 'active');

        // 4. Add a nested object
        JsonMgt.AddJson('customer.address', '{"city":"London","country":"UK"}');

        // 5. Convert back to JSON text
        ResultJson := JsonMgt.WriteObjectToString();
        Message(ResultJson);
    end;
}

The result would be this:

{
  "customer": {
    "name": "Aardvark",
    "id": "C001",
    "status": "active",
    "address": {
      "city": "London",
      "country": "UK"
    }
  }
}

Here is a more advanced example using arrays.

codeunit 50102 "Demo JSON Array Objects"
{
    procedure DemoArrayOfObjects()
    var
        JsonMgt: Codeunit "JSON Management";
        ResultJson: Text;
        JsonArrayText: Text;
    begin
        // Build the array as a JSON string and load it into the collection
        JsonArrayText := '[{"name":"Aardvark","id":"1"},{"name":"Bison","id":"2"}]';
        JsonMgt.InitializeCollection(JsonArrayText);

        // Show the number of items in the array
        Message('Array item count: %1', JsonMgt.GetCollectionCount());

        // Convert the collection back to JSON text
        ResultJson := JsonMgt.WriteCollectionToString();
        Message(ResultJson);
    end;
}

The result of this code:

[
  {
    "name": "Aardvark",
    "id": "1"
  },
  {
    "name": "Bison",
    "id": "2"
  }
]

Here is an advanced example that shows how to update values inside objects already stored in an array.

codeunit 50103 "Demo JSON Object Updates"
{
    procedure DemoUpdateObjectInArray()
    var
        JsonMgt: Codeunit "JSON Management";
        ResultJson: Text;
        FirstObjectText: Text;
        SecondObjectText: Text;
        UpdatedJsonText: Text;
    begin
        // Start by loading a JSON array from text
        JsonMgt.InitializeCollection('[{"name":"Aardvark","id":"1"},{"name":"Bison","id":"2"}]');

        // Read the first two objects from the collection as text
        if not JsonMgt.GetObjectFromCollectionByIndex(FirstObjectText, 0) then
            exit;

        if not JsonMgt.GetObjectFromCollectionByIndex(SecondObjectText, 1) then
            exit;

        // Replace the first object with an updated version
        FirstObjectText := '{"name":"Cobra","id":"1"}';

        // Rebuild the array with the updated object
        UpdatedJsonText := StrSubstNo('[%1,%2]', FirstObjectText, SecondObjectText);

        // Load the updated array back into the codeunit
        JsonMgt.InitializeCollection(UpdatedJsonText);

        // Write the updated array back to JSON text
        ResultJson := JsonMgt.WriteCollectionToString();
        Message(ResultJson);
    end;
}

Results:

[
  {
    "name": "Cobra",
    "id": "1",
    "status": "active"
  },
  {
    "name": "Bison",
    "id": "2"
  }
]

We could create examples of increasing complexity all day, but the takeaway is simple: these tools make it far easier to process large and complex JSON objects in AL.

When using Codeunit 5459, remember to configure your AI-assisted development tools carefully. Specify that you want to avoid any procedures flagged as OnPrem to ensure your code remains cloud-safe. Otherwise, the AI agent may reference methods unavailable in a SaaS Business Central environment.

I’d love to hear how you use the JSON Management codeunit in your own projects. Do you prefer its structured approach, or do you work directly with JSON objects? Share your thoughts in the comments below.