Workflows
A workflow is the definition of a business process — the sequence of steps Flowker follows to complete an operation. Workflows go through a lifecycle:
| Status | Description |
|---|---|
draft | Created and editable. Not yet runnable. |
active | Ready to execute. Structure is locked. |
inactive | Deactivated. No new executions accepted. |
Nodes and edges
Nodes are the individual steps of a workflow — what you might call tasks in business terms. Each node is a unit of work: receive an event, call a service, evaluate a condition, or perform an action. Flowker supports four node types:
| Type | Purpose | When to use |
|---|---|---|
trigger | Entry point for the workflow | Always the first node. Starts execution when an event occurs. |
executor | Calls an external service via a configured executor | When you need to call an external API or integration. |
conditional | Branches execution based on conditions | When the next step depends on the result of a previous one. |
action | Performs a built-in action (log, transform, etc.) | For built-in operations that don’t require external calls. |
Catalog
The catalog is the read-only registry of all built-in providers, executors, and triggers available in Flowker. You cannot create or modify catalog entries — you discover them. Before configuring any integration, browse the catalog to see what’s already available:
- Executors are the specific capabilities you can invoke inside a workflow node (e.g., HTTP requests, data transformations).
- Triggers define the event types that can start a workflow (e.g., webhooks).
- List catalog executors and List catalog triggers to discover executor and trigger types.
- List catalog providers (
GET /v1/catalog/providers) to list all available providers. - Get catalog provider (
GET /v1/catalog/providers/{id}) to get details for a specific provider. - List executors by provider (
GET /v1/catalog/providers/{id}/executors) to list the executors available for a specific provider.
Configurations
Before you can use an executor in a workflow, you need to configure it. An executor configuration defines how Flowker connects to an external service — including the base URL, authentication credentials, and the specific HTTP endpoints to call. Executor configurations go through a lifecycle:
| Status | Description |
|---|---|
unconfigured | Created but not yet configured with connection details. |
configured | Connection details provided, ready to test. |
tested | Connectivity test passed successfully. |
active | Ready to be used in workflow executions. |
disabled | Temporarily taken out of service. |
Provider configurations
Flowker uses a three-tier model for external integrations:
| Tier | What it is | Nature |
|---|---|---|
| Provider | A type of external service (e.g., Midaz, Tracer). | Static — defined in the catalog. |
| Provider Configuration | A configured instance of a provider with credentials and a base URL. | Dynamic — you create and manage these. |
| Executor Configuration | A specific operation on a provider, with endpoints and field mappings. | Dynamic — references a provider configuration. |
active (in use) and disabled (temporarily offline). You can test connectivity at any time to verify the connection is working.
Use the Provider configurations endpoints to create, manage, and test your provider connections.
Templates
Workflow templates are pre-built workflow patterns available in the catalog. Instead of defining a workflow from scratch, you can select a template, fill in its parameters, and create a ready-to-use workflow in seconds. Each template has a parameter schema that defines what inputs it expects (e.g., which provider configuration to use, threshold values). When you retrieve a template, the schema is dynamically enriched — fields that reference provider configurations are populated with your active configurations, so you can pick from a dropdown instead of entering raw UUIDs. To use a template:
- Browse available templates in the catalog.
- Get the template detail to see its parameter schema.
- Optionally validate your parameters before creating.
- Create a workflow from the template.
draft status, so you can review and adjust it before activating.
Executions
An execution is a runtime instance of a workflow. Every time you trigger a workflow, Flowker creates a new execution and processes its nodes in order. Each execution tracks:
executionId— Unique identifier for this run.status— Current state:pending,running,completed, orfailed.stepResults— The output of each node that ran, in order.finalOutput— The aggregated result of the entire execution.
The main status endpoint (
GET /v1/executions/{id}) returns executionId, workflowId, status, currentStepNumber, totalSteps, startedAt, completedAt, and errorMessage. The stepResults and finalOutput fields are only available via the dedicated results endpoint (GET /v1/executions/{id}/results).Idempotency
Every execution request requires an
Idempotency-Key header. This is a UUID you generate and send with each request to uniquely identify it.
If Flowker receives a second request with the same Idempotency-Key, it returns the original response instead of creating a new execution. This makes retries safe — network failures and timeouts won’t result in duplicate runs.
Dashboard
The Dashboard API provides aggregated summaries of your workflows and executions — useful for building operational dashboards and monitoring tools. Use it whenever you need a high-level view of system health without querying individual executions.
- Workflow summary returns totals and breakdowns by status (draft, active, inactive).
- Execution summary returns totals and breakdowns by status, with optional time range and status filters.
GET /v1/dashboards/executions:
- Monitoring execution health — track completion and failure rates over time to spot degradation early.
- Building status pages — surface workflow throughput and success metrics in internal or client-facing dashboards.
- Alerting on failure rate spikes — compare
failed / totalagainst a threshold to trigger alerts before issues cascade.
Audit and compliance
Flowker automatically records an immutable audit trail for every significant action — workflow creation, status changes, execution starts and completions, executor calls, and configuration changes. You don’t need to enable or configure anything; audit logging happens internally. Key properties of the audit system:
- Immutable — audit entries are append-only and cannot be modified or deleted.
- Hash chain integrity — each entry includes a cryptographic hash linking it to the previous entry, making tampering detectable.
- Flexible search — use Search audit events to query events by type, action, result, resource, or date range.
- Chain verification — use Verify hash chain to confirm the audit trail has not been tampered with.
How it all fits together
Flowker’s concepts build on each other in a clear sequence:
- Explore the catalog to discover available providers, executors, triggers, and templates.
- Configure providers to connect Flowker to live instances of external services.
- Configure executors to define the specific operations and endpoints your workflow needs.
- Define workflows — either from scratch or from a template — referencing your executor configurations.
- Execute workflows to run your business process and retrieve results.
- Monitor and audit — use the dashboard for operational summaries and the audit API for compliance.