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 preferservice_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.
Related References¶
- Flow-level docs: Transformations (flows)
- Step types: Step Types
- Orchestrator API: 04-orchestrator-api.md