Skip to content

Transformations

Transformations convert, normalize, and shape payloads inside workflow execution via the Transformers capability provider.

Terminology

A capability provider is an HTTP service that registers with the capability-registry. Workflows use exclusively type: service_call plus capability_name and path for integrations, transforms, and scripts. Built-in control/context steps remain orchestrator-owned. Do not add new first-class integration types.

Service Role

  • Transformers registers transformers.* capabilities.
  • Orchestrator invokes them through service_call (registry discovery).
  • Gateway may still expose a direct transform helper (/v1/transform) for synchronous tooling; workflow design should prefer service_call.

Capabilities

Capability Path
transformers.apply_xslt /applyXSLT
transformers.xml2json /xml2json
transformers.json2xml /json2xml
transformers.apply_liquid /applyLiquid
transformers.csv_to_json /csv2json
transformers.json_to_csv /json2csv
transformers.xml_to_csv /xml2csv
transformers.csv_to_xml /csv2xml
transformers.flatfile_to_xml /flatfile2xml
transformers.xml_to_flatfile /xml2flatfile
transformers.validate_json_schema /validateJsonSchema
transformers.validate_xsd /validateXsd

Microservice page: Transformers.

Reference demo

  • Workflow: flows/workflows/transform_testing_demo.yaml (XSLT)
  • Workflow: flows/workflows/csv_transform_demo.yaml (CSV ↔ JSON)
  • Workflow: flows/workflows/xml_csv_demo.yaml (XML ↔ CSV)
  • Workflow: flows/workflows/flatfile_demo.yaml (BizTalk wizard XSD flatfile ↔ nested XML)
  • Workflow: flows/workflows/json_schema_validate_demo.yaml (JSON Schema)
  • Workflow: flows/workflows/xsd_validate_demo.yaml (XSD)
  • Workflow: flows/workflows/soap_http_xslt_demo.yaml (SOAP HTTP + XSLT)
  • Artifacts under flows/artifacts/transforms/examples/
  • Shows artifact-driven XSLT chain via service_call

Where to Use Transformations

  • Input normalization before policy checks.
  • Canonical payload generation before egress.
  • Response shaping for downstream systems.
  • Enrichment pipelines that combine stored context and inbound payload.

Runtime Considerations

  • Large payload transformations can increase CPU and memory usage.
  • Keep stylesheets/templates versioned with workflows (artifacts).
  • Add trace checkpoints around expensive transformations.
  • Prefer deterministic mappings for easier troubleshooting.
  • Large-track messaging: transforms only via provider service_call (ADR 0006).

Error Handling Patterns

  • Fail fast on invalid mapping configuration.
  • Capture transform input/output in traces when allowed.
  • Use retry only for transient dependency failures, not mapping errors.