BODtoJSON: Simplified Usage & Complete Use Case Guide

Transform complex Infor OAGIS XML Business Object Documents (BODs) into clean Python dictionaries, target API schemas, flat JSON, or streaming NDJSON in one line of code, using defusedxml for secure parsing.

100% Python Standard Library Infor ION Scripting Ready Data Lakehouse & RAG Optimized Optional FastAPI Microservice

Which Method Should I Use?

Pick the function that matches your destination system. All functions automatically strip XML namespaces, handle UTF-8 BOM characters, and remove the administrative OAGIS Verb (Sync, Process, Show, etc.).

Your Use Case Function to Call Return Type Best For
Map BOD directly to a target REST API schema project(xml, verb, schema) list[dict] Infor ION Scripting, third-party SaaS connectors
Work with Python dicts & header metadata to_records(xml, verb, include_header=True) list[dict] Custom business rules, conditional logic in Python
Stream records to Snowflake, Databricks, or Vector DB to_ndjson(xml, verb) str (lines) Data Lakehouses, Kafka/Event Hubs, RAG pipelines
Get a single flat JSON string to_json(xml, verb) str (JSON) Document stores, webhook payloads, logging
Expose conversion as an HTTP microservice uvicorn BODtoJSON.api:app HTTP Response Containerized integration hubs, API gateways

Installation

Core Library vs. Full API Server Secure Parsing (defusedxml)
# 1. Core library only (Ideal for Infor ION Scripting, AWS Lambda, ETL workers)
pip install BODtoJSON==2.3.1

# 2. Core library + FastAPI & Uvicorn REST server
pip install "BODtoJSON[api]==2.3.1"

How XML Keys Are Flattened

Every nested XML tag is joined with an underscore (_) starting from the Noun root inside DataArea:

OAGIS XML Pattern Flattened Key Example Value
Simple element: <DisplayID>PSU000049</DisplayID> PurchaseOrder_PurchaseOrderHeader_DisplayID "PSU000049"
Element with attributes: <ID accountingEntity="3555">PSU000049</ID> ..._DocumentID_ID_#text
..._DocumentID_ID_@accountingEntity
"PSU000049"
"3555"
Repeating sibling tags: multiple <PurchaseOrderLine> ..._PurchaseOrderLine_0_LineNumber
..._PurchaseOrderLine_1_LineNumber
"10"
"20"
Header context (include_header=True) Sync_AccountingEntityID
ApplicationArea_Sender_LogicalID
"3555"
"lid://infor.ln..."

Every Use Case: Copy-Paste Ready

Use Case 1: Infor ION Scripting (Map BOD to Target API Schema) Recommended for ION

Eliminate manual ElementTree namespace parsing, json.loads() loops, and repetitive .get() boilerplate. Define a declarative dictionary and let project() extract header fields (Sync_AccountingEntityID), interpolate strings, map keys, and coerce booleans in one call.

import json
from BODtoJSON import project

# Declarative target schema:
# - "{Key}" interpolates any Noun or Header field (missing keys safely become "")
# - Exact key strings pull values directly
# - Callables (lambda) compute custom expressions
# - Constants (True, "DIMENSION1") pass straight through
SCHEMA = {
    "externalSystemId": "company[{Sync_AccountingEntityID}];DIMENSION1;{ChartOfAccounts_BaseChartOfAccounts_GLNominalAccount}",
    "companyId": "company[{Sync_AccountingEntityID}]",
    "dimensionName": "DIMENSION1",
    "isActive": True,
    "usableInPurchase": lambda r: r.get("ChartOfAccounts_Status_Code") == "Open"
}

# input_var is provided automatically by Infor ION Scripting
items = project(input_var, verb="Sync", schema=SCHEMA, include_header=True)
output_var = json.dumps(items)
Use Case 2: Native Python Dictionary List (Custom Business Logic) No JSON Round-Trip

When you need full Python control (filtering, enrichment, database inserts) without parsing JSON strings back and forth, use to_records(). It raises a standard ValueError on invalid XML.

from BODtoJSON import to_records

records = to_records(xml_payload, verb="Sync", include_header=True)

for rec in records:
    entity = rec.get("Sync_AccountingEntityID")
    po_id = rec.get("PurchaseOrder_PurchaseOrderHeader_DisplayID")
    amount = float(rec.get("PurchaseOrder_PurchaseOrderHeader_ExtendedAmount_#text", 0))
    print(f"Entity {entity} | PO {po_id} | Amount: {amount}")
Use Case 3: Data Lakehouse & Vector DB Streaming (NDJSON) High-Throughput ETL

Generates compact, zero-whitespace, newline-delimited JSON ( terminated). Ideal for Snowflake Snowpipe, Databricks Auto Loader, AWS S3/Glue, and RAG embedding pipelines.

from BODtoJSON import to_ndjson

# Returns one compact JSON object per line, terminated with 

ndjson_stream = to_ndjson(xml_payload, verb="Sync")

# Write directly to S3 / Data Lake staging file
with open("purchase_orders.ndjson", "w", encoding="utf-8") as f:
    f.write(ndjson_stream)
Use Case 4: Standard Flattened JSON String Document Stores

Converts the primary Noun inside DataArea into a single flat JSON string for NoSQL document databases, message queues, or webhook calls.

from BODtoJSON import to_json

flat_json_str = to_json(xml_payload, verb="Sync")
print(flat_json_str)
Use Case 5: Multi-Record Batch BODs Automatic Unpacking

When ERP LN publishes a batch BOD containing multiple sibling Nouns inside DataArea (e.g., 50 <PurchaseOrder> blocks in one SyncPurchaseOrder message), to_ndjson(), to_records(), and project() automatically unpack every Noun into its own record.

from BODtoJSON import to_records, to_ndjson

# Batch XML with 25 <ItemMaster> elements under <DataArea>
items = to_records(batch_item_xml, verb="Sync")
print(f"Unpacked {len(items)} individual records")

# Or emit 25 compact NDJSON lines in one call
lines = to_ndjson(batch_item_xml, verb="Sync")
Use Case 6: Custom Delimiter or Non-Standard Root Node Advanced Configuration

Instantiate BODConverter directly if you want dot-notation keys (PurchaseOrder.Header.ID) instead of underscores, or need to target a custom container node.

from BODtoJSON import BODConverter

# Use '.' instead of '_' for flattened keys
dot_converter = BODConverter(pnode="DataArea", separator=".")
records = dot_converter.to_records(xml_payload, verb="Process")

print(records[0]["PurchaseOrder.PurchaseOrderHeader.DisplayID"])
Use Case 7: REST Microservice Tier (FastAPI) Optional [api] Extra

Run BODtoJSON as a standalone HTTP service for non-Python applications or integration platforms.

# Start the server locally or inside Docker
uvicorn BODtoJSON.api:app --host 0.0.0.0 --port 8000

# Available Endpoints:
# POST /convert/ndjson?verb=Sync   (Body: raw text/plain XML -> application/x-ndjson)
# POST /convert/json?verb=Sync     (Body: raw text/plain XML -> application/json)
# POST /project                    (Body: {"xml": "...", "verb": "Sync", "schema_map": {...}})
# GET  /health                     (Service health check)
Use Case 8: Legacy Code Compatibility Deprecated in v3.0.0

Existing scripts calling convert(xml, verb) continue to work without breaking changes, routing internally to to_json() while logging a non-blocking DeprecationWarning.

from BODtoJSON import convert

# Works seamlessly, emits DeprecationWarning (scheduled for removal in v3.0.0)
result = convert(xml_payload, verb="Sync")

Complete API Reference

Signature Parameters Returns
project(bod_xml, verb, schema, include_header=True, coerce_booleans=True) bod_xml (str): Raw OAGIS XML.
verb (str): OAGIS Verb to strip (e.g. "Sync").
schema (dict): Target field mapping rules.
include_header (bool): Include ApplicationArea & Verb fields.
coerce_booleans (bool): Convert "true"/"false" strings to bool.
List[Dict[str, Any]]
to_records(bod_xml, verb, include_header=False) bod_xml (str): Raw OAGIS XML.
verb (str): OAGIS Verb to strip.
include_header (bool): Merge header metadata into each record.
List[Dict[str, Any]]
to_ndjson(bod_xml, verb) bod_xml (str): Raw OAGIS XML.
verb (str): OAGIS Verb to strip.
str (Newline-delimited compact JSON)
to_json(bod_xml, verb) bod_xml (str): Raw OAGIS XML.
verb (str): OAGIS Verb to strip.
str (Flat JSON string)
BODConverter(pnode='DataArea', separator='_') pnode (str): Container tag holding Verb & Noun.
separator (str): Delimiter between nested tag names.
BODConverter instance

Interactive Output Previewer

Test how your OAGIS XML flattens directly in the browser before deploying to Infor ION.