Xema Workflows Documentation

Welcome to the Xema Workflows documentation. This guide explains how workflows power the Xema platform, enabling automated, intelligent, and human-guided software delivery pipelines.

What Are Workflows?

Workflows are declarative, YAML-based automation specifications that orchestrate multi-stage software delivery processes. They combine:

• Deterministic execution — Same workflow + input always produces the same output
• Intelligent automation — LLM agents, human approval gates, and artifact review
• Flexible integration — Connect external systems (GitHub, GitLab, Jira, Slack, etc.)
• Production-grade reliability — Built on the Xema Workflow Runtime for fault-tolerant, long-running processes

Key Capabilities

Quick Links

• Concepts & Fundamentals — DSL, templates, phases, artifacts
• Features & Capabilities — Available workflow features and when to use them
• Integration Guide — How external systems trigger and interact with workflows
• Templates System — How templates work and how to customize them
• Expressions & Data Flow — Inputs, outputs, variable binding, and expressions
• API Reference — REST API endpoints for workflow management
• Briefcase — Attach run-scoped context (files, references, vars, tools) at dispatch
• Workspace Manifests — Author and manage workspace manifests for agent jobs

For Different Audiences

Product Managers & Business Users

Start with Features & Capabilities to understand what workflows enable for your product. Then read Integration Guide to see how users interact with external systems.

Developers & Technical Integrators

Begin with Concepts & Fundamentals to understand DSL structure. Then explore Integration Guide and Expressions & Data Flow for technical implementation details.

DevOps & Platform Engineers

See Concepts & Fundamentals for architecture overview, then review the execution model and workflow runtime configuration sections.

Core Principles

1. Declarative, not imperative — You describe what should happen; Xema handles how
2. Type-safe and fail-fast — Invalid workflows are rejected at compile time, not runtime
3. Deterministic & reproducible — Same inputs always produce identical execution plans
4. Single ingress edge — All external webhooks flow through a normalized integration layer
5. Human-in-the-loop — Approval gates and human review are first-class features
6. Scalable — Built on the Xema Workflow Runtime for horizontal scaling and fault tolerance

Architecture Overview

1┌─────────────────────────────────────────────────────────────┐
2│  Workflow Authoring Layer                                   │
3│  (YAML DSL v1alpha1)                                        │
4└────────────────────┬────────────────────────────────────────┘
5                     │
6                     ▼
7┌─────────────────────────────────────────────────────────────┐
8│  Compilation Layer                                          │
9│  (Validation, Action Pinning, Job DAG)                     │
10│  ↓ Produces deterministic CompiledRun                       │
11└────────────────────┬────────────────────────────────────────┘
12                     │
13                     ▼
14┌─────────────────────────────────────────────────────────────┐
15│  Dispatch & Trigger Layer                                   │
16│  (Webhook, Schedule, Manual)                                │
17└────────────────────┬────────────────────────────────────────┘
18                     │
19                     ▼
20┌─────────────────────────────────────────────────────────────┐
21│  Execution Engine (Xema Workflow Runtime)                    │
22│  (Job Scheduling, Approval Gates, Agent Invocation)        │
23└────────────────────┬────────────────────────────────────────┘
24                     │
25                     ▼
26┌─────────────────────────────────────────────────────────────┐
27│  Activity Runtime                                           │
28│  (Agent Execution, Artifact Emission, Reviews)              │
29└─────────────────────────────────────────────────────────────┘
30
31External Systems ──┐
32(GitHub, GitLab,   ├──> Connector Gateway ─────> Webhook Dispatcher
33 Jira, Slack, ...) └────────────────────────────────> Workflow Trigger

Getting Started

1. Read Concepts & Fundamentals to understand workflow structure
2. Review Features & Capabilities to decide which features you need
3. Check Integration Guide to understand how your system interacts
4. Explore Expressions & Data Flow to learn about inputs/outputs
5. Customize Templates for your deliverables

FAQ

Q: Can I use workflows without coding?
A: Yes! Workflows are YAML-based and declarative. You describe what you want to happen, and Xema handles the implementation. No code required.

Q: How do I trigger workflows from external systems?
A: See Integration Guide. Workflows can be triggered by webhooks from GitHub, GitLab, Jira, Slack, and any system that can send HTTP POST requests.

Q: What if a workflow fails?
A: Workflows are built on the Xema Workflow Runtime, which provides automatic retry logic, failure handling, and human intervention options. See Features & Capabilities for details.

Q: How long can workflows run?
A: Xema workflows can run for months or years. Long-running workflows (human approvals, multi-phase pipelines) are fully supported.

Q: Can workflows call other workflows?
A: Yes! Workflows can call other workflows as child workflows, enabling complex hierarchical automation.

Need Help?

• Technical issues — Check the API Reference
• Integration questions — See Integration Guide
• Template customization — Review Templates System
• Expression syntax — Explore Expressions & Data Flow

Last Updated: April 2026
Version: 1.0 — Xema Workflows System