Wiring Render & Mail

Flow depends on sibling services over HTTP. Render engines and output providers are both name-routed.

Render engines

Jobs pick an engine with optional render.engine (default oxykit-render). Built-in and third-party engines all implement IDocumentRenderer from OxyKit.Flow.Abstractions — third parties do not edit Flow host code.

Config (Render:Engines)

"Render": {
  "Engines": {
    "oxykit-render": {
      "Kind": "oxykit",
      "BaseAddress": "http://localhost:5066/",
      "ApiKey": "dev-local-key"
    },
    "crystal": {
      "Kind": "assembly",
      "Assembly": "plugins/MyCo.Flow.Crystal.dll",
      "Type": "MyCo.Flow.Crystal.CrystalDocumentRenderer"
    }
  }
}

Kind	Meaning
oxykit (default when omitted)	Built-in adapter via OxyKit.Render.Client — requires BaseAddress
assembly	Load DLL + type implementing IDocumentRenderer — requires Assembly + Type

Rule	Notes
Config key	Must match IDocumentRenderer.Name (e.g. "crystal")
Package for plugins	Reference OxyKit.Flow.Abstractions only (not the Web host)
Assembly path	Absolute, or relative to content root / app base directory
Construction	ActivatorUtilities — ctor may take HttpClient, IConfiguration, etc.
Legacy	OxyKit.Render:BaseAddress / ApiKey still seeds default oxykit-render

Unknown render.engine values are rejected at job create.

Third-party recipe (no host fork)

1. Class library → package/project reference OxyKit.Flow.Abstractions
2. Implement IDocumentRenderer (HTTP to your sidecar; keep generators out of Flow)
3. Drop the DLL next to Flow (e.g. plugins/)
4. Add a Render:Engines:{name} entry with Kind=assembly
5. Jobs: "render": { "engine": "crystal", "input": "...", "output": "...", "body": { } }

Mail (mail output)

• Base URL (local default http://localhost:5026)
• API key with Sender (or Admin) role
• Empty OxyKit.Mail:ApiKey is a common local misconfiguration — jobs fail at deliver

Mail’s accept contract applies: treat accepted as success; do not re-send.

Outputs

Provider	Notes
file	Filesystem path
mail	HTTP to Mail
ftp / sftp	Named profiles under Outputs:Transfer:Profiles

Unknown provider values are rejected at job create (same pattern as render engines).

Local order

1. Render sidecar(s) on their ports (OxyKit.Render and/or your plugin’s API)
2. Mail on :5026 (if using mail)
3. Flow on :5077 with Render:Engines (+ outputs) configured

See Local compose for the golden-path checklist.