DEV Community

Alone Star
Alone Star

Posted on

LightESB PlatformHttp v1.0.0: DS Data Transform Guide

#api #backend #data #tutorial

Metadata

  • Applicable Version: PlatformHttp@v1.0.0
  • Related Service: PlatformHttp@v1.0.0@complex-json-transform-route.xml

PlatformHttp v1.0.0 provides a practical DS data transform route for complex order payloads.

The route uses conditionaltransform to decide whether to run the transform and returns the converted JSON directly to the caller.

Background and Goal

For integration scenarios, upstream payloads are often deeply nested and hard to consume directly.

This route targets a stable pattern:

  • keep a clear HTTP Listener as the request entry
  • flatten multi-level order JSON into business-friendly fields
  • prepare transformed data for downstream forwarding
  • keep response write-back stable with JSON encoding handling

Route and Configuration Breakdown

1) HTTP Listener request entry

From complex-json-transform-route.xml:

<from uri="undertow:http://0.0.0.0:{{server.port}}/api/transform/complex-order?httpMethodRestrict=POST" />
Enter fullscreen mode Exit fullscreen mode

From common.config.properties:

server.port=18081
HTTP.Listener=true
system.components=undertowhttp,streamcache,jsontransform,conditionaltransform
Enter fullscreen mode Exit fullscreen mode

Resulting request endpoint:

  • POST http://localhost:18081/api/transform/complex-order

2) Conditional transform switch

The route invokes:

<to uri="conditionaltransform:input?skipOnError=true"/>
Enter fullscreen mode Exit fullscreen mode

The transform behavior is controlled by:

input-transform=true
input-transform.file=input-transform-with-import.ds
Enter fullscreen mode Exit fullscreen mode

Meaning:

  • when input-transform=true, DS transform executes
  • input-transform-with-import.ds is used as the input transform script
  • when transform fails and skipOnError=true, the route continues without hard stop

3) DS script and shared function import

Main script:

  • lightesb-camel-app/PlatformHttp/v1.0.0/input-transform-with-import.ds

Shared function library:

  • lightesb-camel-app/TransformDS/common-functions.ds

The script imports common functions to keep rules modular:

local lib = import 'lightesb-camel-app/TransformDS/common-functions.ds';
Enter fullscreen mode Exit fullscreen mode

Typical mappings include:

  • customer name via lib.formatFullName(...)
  • shipping address via lib.formatAddress(...)
  • line totals via lib.calculateLineTotal(...)
  • normalized financial values via lib.formatAmount(...)

4) Response write-back

The route finishes with:

<process ref="jsonResponseProcessor"/>
Enter fullscreen mode Exit fullscreen mode

This helps keep JSON response output stable for UTF-8 and content formatting during response write-back.

Request and Response Examples

Request Example

Run from 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"
Enter fullscreen mode Exit fullscreen mode

Response Example (key fields)

A successful response contains transformed fields such as:

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

Quick verification 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}'
Enter fullscreen mode Exit fullscreen mode

Common Issues and Troubleshooting

1) Port is not reachable

Check:

  1. HTTP.Listener=true
  2. server.port=18081
  3. no process conflicts on port 18081

2) Request method rejected

The route uses httpMethodRestrict=POST; call must be POST.

3) No transform applied

Check:

  • input-transform=true
  • input-transform.file=input-transform-with-import.ds
  • DS file path and syntax are valid

4) Import file not found

input-transform-with-import.ds imports:

  • lightesb-camel-app/TransformDS/common-functions.ds

Ensure this file exists and path is correct relative to runtime resolution.

Summary

PlatformHttp v1.0.0 offers a clear DS transform baseline:

  • stable HTTP Listener request entry
  • configuration-driven transform switch with conditionaltransform
  • reusable DS function library via import
  • predictable response write-back through jsonResponseProcessor

This pattern is suitable for complex JSON flattening and can be extended with validation, auth checks, and downstream forwarding policies.

Links

Top comments (0)