Workflows

Workflows are programmable functions that execute at key decision points in the MonetizationOS platform, allowing you to implement custom business logic beyond what's possible through configuration alone. Written in TypeScript and running at the edge in V8 isolates, workflows provide low-latency, type-safe extensibility for controlling access, provisioning plans, customizing content, and integrating with external systems.

Why Workflows?

While MonetizationOS provides powerful configuration options for plans, features, and surfaces, real-world monetization requirements often demand dynamic, context-aware decision making. Workflows bridge this gap by enabling:

• Dynamic decision logic: Make access and provisioning decisions based on runtime data like JWT claims, geolocation, or external API responses
• Integration capabilities: Connect with payment providers, CRMs, analytics platforms, and other external services
• Custom business rules: Implement complex logic that would be impossible or impractical to express through configuration or visual rules builders
• Temporal and contextual awareness: React to time of day, user behavior patterns, A/B test assignments, and request context
• Side effects and orchestration: Trigger downstream actions, send notifications, and coordinate multi-step processes

Workflow Types

MonetizationOS provides distinct workflow types, each designed for specific extension points in the platform:

• Action Workflows: Respond to system or custom triggers asynchronously for integrations, notifications, and analytics
• Component Workflows: Customize individual surface components with access to parent surface properties
• Dynamic Provisioning Workflows: Assign plans to users dynamically based on identity, context, or external data at decision time
• Endpoint Workflows: Handle HTTP requests to custom API endpoints with full access to identity and integrations
• Feature Workflows: Override feature property values using custom logic, external APIs, or runtime conditions
• Surface Workflows: Control surface behavior, HTTP responses, and properties passed to child components

How Workflows Work

Workflows execute in a secure, sandboxed environment at Cloudflare's edge network, providing:

• Low latency: Execute close to your users globally, typically in under 50ms
• Type safety: Full TypeScript support with autocomplete for arguments, return types, and platform utilities
• Isolation: Each workflow runs in its own V8 isolate for security and performance
• Modern JavaScript: Support for latest ECMAScript features and standard Web APIs (fetch, Crypto, URL, etc.)

Execution Flow

Synchronous workflows (Dynamic Provisioning, Feature, Surface, Component) execute inline during API requests:

API Request → Authentication → Dynamic Provisioning Workflows → Feature Workflows → Surface/Component Workflows → Response

Action workflows run in response to triggers without blocking the original event:

Event/Trigger → Action Workflow → External Integration/Side Effect

Endpoint workflows handle incoming HTTP requests directly:

HTTP Request → Routing → Endpoint Workflow → HTTP Response

Developer Experience

Workflows are developed in the MonetizationOS console with:

• Inline code editor: Write TypeScript directly in the browser with syntax highlighting
• Type definitions: Automatically generated TypeScript types based on your organization's configuration
• Workflow-specific APIs: Access to utils for identity management, triggers, buckets, integrations, and offers
• Environment variables: Secure storage for API keys and configuration via the env object
• Testing in Preview: Test workflows in Preview environments before deploying to Live environments

Common Patterns

• Conditional Plan Assignment: Use Dynamic Provisioning workflows to assign plans based on JWT claims, subscription status, or external API lookups.
• External Data Integration: Feature workflows can fetch data from external APIs to dynamically compute feature properties.
• Custom Metering Logic: Surface and Component workflows can implement sophisticated metering using the metering APIs and request context.
• Event-Driven Integrations: Action workflows respond to platform events (plan changes, decisions, counter updates) to sync state with external systems.
• API Gateway Patterns: Endpoint workflows create custom API routes for webhooks, integrations, offer redemptions, or specialized access patterns.

Learn More

Getting Started guides

References

API references

Workflow references

Admin Guides