Gestión de JSON en Business Central: Dominando JSON Management estándar

Trabajar con datos JSON en Business Central es una tarea habitual cuando interactuamos con APIs, servicios externos o almacenamos información estructurada. Afortunadamente, Microsoft ofrece una herramienta estándar que hace esta labor mucho más sencilla: la Codeunit "JSON Management".

En este post, te mostraré cómo aprovechar sus capacidades para manipular datos JSON de manera eficiente. Además, integraremos algunas funciones útiles para simplificar tareas cotidianas.

¡Vamos manos a la obra! 😤

🧩 ¿Qué es la `Codeunit JSON Management`?

La Codeunit "JSON Management" es una herramienta estándar de Business Central que facilita el manejo de datos en formato JSON. Permite trabajar con objetos, colecciones y valores individuales de manera clara y eficiente, sin necesidad de escribir lógica compleja desde cero.

🎯 Principales capacidades:

Inicializar objetos JSON
Extraer y modificar valores
Trabajar con arreglos JSON (JsonArray)
Convertir entre texto y objetos JSON

Esta Codeunit es esencial cuando necesitas comunicarte con servicios externos a través de APIs REST o cualquier fuente que use JSON como formato de intercambio de datos.

🧩 Extrayendo datos con `GetValueText`

Una de las tareas más comunes al trabajar con JSON es extraer el valor de una clave específica. Veamos cómo hacerlo con la Codeunit JSON Management:

procedure GetValueText(Json: Text; Tag: Text) ReturnValue: Text;
var
    JSONManagement: Codeunit "JSON Management";
begin
    Clear(JSONManagement);
    JSONManagement.InitializeObject(Json);
    ReturnValue := JSONManagement.GetValue(Tag);
end;

🔍 ¿Qué ocurre aquí?

Inicializamos un objeto JSON usando InitializeObject.
Buscamos el valor asociado a la clave indicada con GetValue(Tag).
Devolvemos el valor encontrado como un Text.

🛠️ Aplicación práctica:
Supongamos que recibes un JSON con información de un pedido y necesitas el CustomerName. Con esta función, lo obtienes en una sola llamada.

🧱 Convirtiendo `Text` en `JsonObject` con `GetValueJsonObject`

A veces, el valor asociado a una clave no es un texto simple, sino un objeto JSON anidado. En esos casos, necesitamos convertirlo a un JsonObject:

procedure GetValueJsonObject(Json: Text; Tag: Text) ReturnValue: JsonObject;
var
    ValueText: Text;
begin
    ValueText := this.GetValueText(Json, Tag);
    ReturnValue.ReadFrom(ValueText);
end;

🔍 ¿Qué hace esta función?

Obtiene el valor como Text utilizando la función GetValueText.
Convierte el texto en un JsonObject mediante ReadFrom(ValueText).

🛠️ Aplicación práctica:
Cuando una respuesta JSON de una API devuelve un objeto con múltiples propiedades, esta función permite manejarlo como un JsonObject para acceder fácilmente a sus campos.

📦 Accediendo a elementos de un `JsonArray` con `GetValueFromJsonArray`

Los datos JSON suelen contener listas o arreglos, por ejemplo, una lista de productos o transacciones. Para acceder a un elemento específico por su índice, usamos esta función:

procedure GetValueFromJsonArray(Json: Text; Index: Integer) ReturnValue: Text;
var
    JSONManagement: Codeunit "JSON Management";
begin
    Clear(JSONManagement);
    JSONManagement.InitializeCollection(Json);
    JSONManagement.GetObjectFromCollectionByIndex(ReturnValue, Index);
end;

🔍 ¿Qué sucede aquí?

Inicializamos una colección JSON con InitializeCollection.
Accedemos al elemento del índice solicitado con GetObjectFromCollectionByIndex.
Devolvemos el valor en formato Text.

🛠️ Aplicación práctica:
Ideal cuando se trabaja con listas de artículos, líneas de factura o cualquier conjunto de datos repetidos dentro de un JSON.

✅ Verificando la existencia de un valor con `HasValue`

Antes de acceder a una clave en un JSON, es importante comprobar si existe. Esta función se encarga de hacerlo:

procedure HasValue(Json: Text; Tag: Text) ReturnValue: Boolean
var
    ValueText: Text;
begin
    Clear(ReturnValue);
    ValueText := this.GetValueText(Json, Tag);
    if ValueText <> '' then
        ReturnValue := true;
end;

🔍 ¿Cómo funciona?

Busca el valor de la clave solicitada usando GetValueText.
Comprueba si el valor está vacío y devuelve true si existe.

🛠️ Aplicación práctica:
Es muy útil al trabajar con estructuras JSON dinámicas, donde no todas las claves están garantizadas.

🚀 ¿Por qué usar la `Codeunit JSON Management`?

🌟 Ventajas clave

Integración nativa: No necesitas bibliotecas externas, todo se gestiona dentro de Business Central.
Código simplificado: Funciones claras y bien definidas para tareas comunes.
Eficiencia garantizada: Operaciones optimizadas por Microsoft, listas para producción.

🌐 Aplicaciones prácticas

Integración con APIs REST: Procesamiento de respuestas JSON en integraciones con CRM, e-commerce y otros sistemas.
Procesamiento de datos estructurados: Análisis de grandes volúmenes de información en formato JSON.
Exportación e importación de datos: Generación y consumo de JSON para intercambio de datos con aplicaciones externas.

🎯 Ejemplo práctico:
Imagina una integración con un sistema de logística. Al recibir un JSON con el estado de un envío, puedes usar la Codeunit JSON Management para extraer el campo status y reflejarlo en Business Central.

🏁 Conclusión

La Codeunit "JSON Management" de Business Central es una herramienta poderosa que facilita la manipulación de datos estructurados en formato JSON. Con las funciones descritas, puedes extraer, convertir, verificar y procesar información de manera clara y eficiente.

Si quieres ver el código completo, está en GitHub.

¡Hasta la próxima!

🧩 ¿Qué es la Codeunit JSON Management?