Technical article

PlatformHttp v1.0.0: config-driven DS transform for complex order JSON

PlatformHttp v1.0.0 ships a practical DS data transform route for complex order payloads. An HTTP Listener accepts the nested order JSON, conditionaltransform runs the conversion only when configuration enables it, and the converted JSON is written straight back to the caller.

Sample: example/routes/PlatformHttp/v1.0.0Docs: docs/components/04-transform-components.mdRepository: github.com/nghxni/lightesb-camel

Deeply nested order JSON is expensive to consume

In integration scenarios, upstream payloads arrive with many levels and fields that downstream systems cannot use directly. The route targets a stable pattern: keep a clear HTTP Listener as the request entry, flatten multi-level order JSON into business-friendly fields, prepare the transformed data for downstream forwarding, and keep response write-back stable with JSON encoding handling.

Route breakdown: entry, switch, script, write-back

HTTP Listener entry

complex-json-transform-route.xml listens on undertow:http://0.0.0.0:{{server.port}}/api/transform/complex-order?httpMethodRestrict=POST. With server.port=18081 and HTTP.Listener=true in common.config.properties, the endpoint is POST http://localhost:18081/api/transform/complex-order; system.components loads undertowhttp, streamcache, jsontransform, and conditionaltransform.

Conditional transform switch

The route invokes conditionaltransform:input?skipOnError=true. When input-transform=true the DS transform executes; input-transform.file=input-transform-with-import.ds selects the script. If the transform fails and skipOnError=true, the route continues without a hard stop.

DS script with shared functions

input-transform-with-import.ds imports lightesb-camel-app/TransformDS/common-functions.ds to keep rules modular: lib.formatFullName(...) builds the customer name, lib.formatAddress(...) the shipping address, lib.calculateLineTotal(...) line totals, and lib.formatAmount(...) normalized financial values.

Stable response write-back

The route finishes with a jsonResponseProcessor reference, which keeps JSON response output stable for UTF-8 and content formatting during write-back — the caller receives the converted JSON directly.

Verify with curl

Post the bundled test payload from the repository root:

curl -X POST "http://localhost:18081/api/transform/complex-order" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v1.0.0/test.json"

A successful response returns the flattened business fields:

{
  "orderId": "ORD-2024-003",
  "customerName": "张明华",
  "items": [
    {
      "productId": "PROD-001",
      "lineTotal": 16198.2
    }
  ],
  "financial": {
    "currency": "CNY"
  }
}

Check the key fields in one line with jq:

curl -s -X POST "http://localhost:18081/api/transform/complex-order" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v1.0.0/test.json" | jq '{orderId, customerName, itemCount: (.items|length), currency: .financial.currency}'

When it does not transform

Port not reachable: confirm HTTP.Listener=true, server.port=18081, and that no other process holds port 18081.
Method rejected: the entry sets httpMethodRestrict=POST, so the call must be POST.
No transform applied: check input-transform=true, input-transform.file=input-transform-with-import.ds, and that the DS file path and syntax are valid.
Import file not found: input-transform-with-import.ds depends on lightesb-camel-app/TransformDS/common-functions.ds — the file must exist and resolve correctly at runtime.

Transform components guide PlatformHttp v1.0.0 sample