Summary

Document a recommended pattern for composing workflows in Kubernetes using SonataFlow where a “main” workflow invokes other workflows (subflows) as standard microservices through OpenAPI, and service locations are resolved at runtime via SonataFlow Operator service discovery.

Goals / What to Cover

1. Pattern overview: How to consume other workflows running in the same cluster using SonataFlow.

1. Main workflow calls: Treat subflows as regular microservices exposed by HTTP; call them via OpenAPI.

1. Subflow development: Develop subflows locally and generate their OpenAPI contracts during development.

1. Spec management: Import generated OpenAPI files into the main workflow project under specs/.

1. Invocation wiring: Use the state function openapi mechanism in the main workflow to call subflows.

1. Runtime resolution: Configure endpoints via SonataFlow Operator Service Discovery so no hard-coded URLs are required.

Deliverables

• A new docs page (and sidebar entry) titled:
  “Composing Workflows: Calling Subflows via OpenAPI + Service Discovery”

• A minimal, end-to-end example (repo or snippet pack) demonstrating:

• • One main workflow calling one subflow via OpenAPI.

• • Local generation of the subflow’s OpenAPI file and placement into specs/.

• • Deployment to Kubernetes where the main workflow resolves the subflow address via Operator service discovery.

• A checklist/reference for customers adopting the pattern.

 

Outline / Proposed Doc Structure

1. Why this pattern

• • Decouple teams; independent lifecycle for subflows.

• • Contract-first integration using OpenAPI.

• • Environment-agnostic via service discovery in K8s.

1. Architecture at a glance

• • Main workflow ⇄ Subflow(s) over HTTP

• • OpenAPI contract shared to main workflow (specs/)

• • Operator-backed discovery provides runtime URLs

1. Subflow: develop & generate OpenAPI

• • Run subflow locally.

• • Generate/export OpenAPI file (tooling specifics left to stack; e.g., Quarkus/SpringDoc).

• • Version and publish the contract (optional guidance).

1. Main workflow: import contract

• • Place subflow-a.yaml under specs/.

• • Reference by function using openapi type.

1. Main workflow: call the subflow

• • Example (YAML) using functionRef with openapi:

functions:
  - name: subflowA
    operation: specs/subflow-a.yaml#POST:/v1/process
    type: openapistates:
  - name: call-subflow-a
    type: operation
    actions:
      - functionRef:
          refName: subflowA
          arguments:
            input: "${ .payload }"
    end: true

Non-Goals / Out of Scope

• Implementing a generic code generator for subflows.

• Deep dives into specific framework plugins (keep tool-agnostic where possible; link out for details).

• Async/messaging patterns (covered elsewhere).

Dependencies / Inputs

• A minimal sample subflow exposing at least one HTTP endpoint.

• The SonataFlow Operator running in a test cluster for service discovery validation

References

• OpenAPI-based orchestration (state function openapi):
  https://sonataflow.org/serverlessworkflow/main/service-orchestration/orchestration-of-openapi-based-services.html

• Operator Service Discovery:
  https://sonataflow.org/serverlessworkflow/main/cloud/operator/service-discovery.html