How to Read JSON Using JSON Parsing 4GL Functions in Sage X3

Since the 2023R2 release, Sage X3 has introduced JSON parsing 4GL functions, enabling developers to efficiently fetch and process data from JSON-formatted strings. This blog explores the key JSON parsing functions—ParseInstance, Contains$, and Select$—and provides practical examples and best practices for their use.

Introduction to JSON Parsing in Sage X3

JSON (JavaScript Object Notation) is a lightweight data-interchange format widely used for structured data. With Sage X3’s JSON parsing functions, you can parse JSON strings, check for specific properties, and extract values seamlessly within 4GL scripts. These functions are particularly useful for integrating external data or processing structured inputs.

New Stuff :- Implementing User-Specific Access Control in Sage X3 for the Receipt Line Inquiry Screen

Key JSON Parsing Functions

1.ParseInstance
The ParseInstance function is used to parse a JSON string into an object that can be queried or manipulated.

Syntax:
ParseInstance OBJECT With JSON_OBJECT

• OBJECT: The object used to parse the input JSON.
• JSON_OBJECT: The JSON string to be parsed (recommended to use Clbfile).

Example:

This code parses a simple JSON string {“msg”:”Hello World!”} into the OBJ instance for further processing.

2.Contains$
The Contains$ function checks if a parsed JSON object contains a specific property, returning 1 if the property exists and 0 if it does not.

Syntax:
RETURN_VALUE = JSON_OBJECT.Contains$(JSON_POINTER)

• RETURN_VALUE: Integer (1 for exists, 0 for does not exist).
• JSON_OBJECT: The parsed JSON object.
• JSON_POINTER: The JSON pointer expression to check (use square brackets for array indices).

Example:

This example checks for the msg property and the second element in the list array.

3.Select$
The Select$ function retrieves the value of a specific property from a parsed JSON object.

Syntax:
RETURN_VALUE = JSON_OBJECT.Select$(JSON_PATH)

• RETURN_VALUE: String containing the selected property’s value.
• JSON_OBJECT: The parsed JSON object.
• JSON_PATH: The JSON path expression to select (use square brackets for array indices).

Example:
Procedure to select properties

This code extracts the msg property and the second element of the list array.

Best Practices for JSON Parsing

• To handle JSON data efficiently, especially when dealing with arrays or dynamic data, follow these best practices:
• Use Clbfile for JSON Strings: Store JSON strings in Clbfile variables to handle large or complex JSON data effectively.
• Always Free Memory: Use FreeGroup to release memory allocated to the JSON object and prevent memory leaks.
• Iterate Arrays with Loops: For JSON arrays, use a WHILE loop with Contains$ to dynamically check and extract elements.

Example (Iterating an Array):

This script iterates through the list array, extracting each element until no more elements are found.

Conclusion
Sage X3’s JSON parsing 4GL functions (ParseInstance, Contains$, and Select$) provide a robust way to handle JSON data within your scripts. By following the syntax and best practices outlined above, you can efficiently parse, query, and extract data from JSON strings. Always ensure proper memory management with FreeGroup and use loops for dynamic array processing to make your code scalable and maintainable.