Skip to content

Transformations

Transformations are used to convert, normalize, and shape payloads inside workflow execution.

Service Role

  • Dedicated Transformers service handles transformation operations.
  • Gateway exposes a direct transform endpoint (/v1/transform) for synchronous usage.
  • Orchestrator uses transformation steps as part of workflow execution.

Typical Transformation Types

  • XSLT for XML-to-XML mappings.
  • XML to JSON conversion.
  • JSON to XML conversion.
  • Template-based rendering (for example Liquid-style mapping scenarios).

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.
  • Add trace checkpoints around expensive transformations.
  • Prefer deterministic mappings for easier troubleshooting.

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.
  • Flow-level step docs: ../../flows/reference/02-step-types.md
  • Orchestrator API: 04-orchestrator-api.md