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 a zero-dependency stdlib parser for secure parsing.
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
# 1. Core library only (Ideal for Infor ION Scripting, AWS Lambda, ETL workers) pip install BODtoJSON==2.4.0 # 2. Core library + FastAPI & Uvicorn REST server pip install "BODtoJSON[api]==2.4.0"
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_AccountingEntityIDApplicationArea_Sender_LogicalID |
"3555""lid://infor.ln..." |
Every Use Case: Copy-Paste Ready
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)
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}")
Generates compact, zero-whitespace, newline-delimited JSON (\n 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 \n
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)
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)
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")
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"])
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)
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.