Creating Stateful Workflows

Stateful workflows are the crown jewel of Mockzilla. They allow you to move beyond static JSON files and build simulations that maintain state, use in-memory databases, and execute complex business logic—all without writing a single line of backend code.

The Workflow Hierarchy

To build a workflow, you need to understand two primary concepts: Scenarios and Transitions.

Scenario

The "Container".

A Scenario is an isolated sandbox. It has its own State (variables) and Mini-DB (tables). Changes in one scenario never affect another.

Transition

The "Logic".

A Transition is a rule: "If the request matches this Path, Method, and Condition, then apply these Effects and return this Response."

Anatomy of a Transition

A Transition is composed of four main parts. Think of it as a specialized "If/Then" statement for your API.

1. Matching (Path & Method)

The first step is identifying which request this transition applies to.

Path: e.g., /login or /cart/add.
Method: GET, POST, PUT, DELETE, etc.

2. Conditions (The "If")

Conditions are optional rules that must be met for the transition to fire.

Example: input.body.password == "secret123"
Operators: eq, neq, exists, gt, lt, contains.

3. Effects (The "Side-Effect")

Effects are changes made to the Scenario's internal state or database.

state.set: Update a variable (e.g., isLoggedIn = true).
db.push: Add a row to a table (e.g., add item to cart table).

4. Response (The "Result")

The JSON body and Status Code returned to the frontend.

Example: 200 OK with {"message": "Welcome back!"}.

Step-by-Step: Your First Workflow

Let's build a simple Counter API that increments a value every time it's called.

Create a Scenario

Go to Workflows and create a new scenario named Counter Demo.

Initialize State

Open the State Inspector and set a variable count to 0.

Add the Increment Transition

Create a new transition:

Path: /increment
Method: POST
Effect: state.set → {"count": "(math state.count + 1)"}
Response: {"new_count": "(state.count)"}

"Create a counter workflow scenario with a POST /increment endpoint that increments a state variable called count and returns the new value."

The AI will autonomously create the scenario, initialize the state, and configure the transition for you.

Advanced Power: The Mini-DB

While state is great for simple variables, db allows you to manage collections of data.

// Example: Adding an item to a cart
{
  "type": "db.push",
  "table": "cart",
  "value": {
    "id": "{{input.body.product_id}}",
    "name": "{{input.body.name}}",
    "added_at": "{{now}}"
  }
}

Relational Lookups

You can query your database directly in your responses or effects using predicates:

{{db.users[id=1].name}} - Finds user with ID 1.
{{db.cart[0].id}} - Gets the ID of the first item in the cart.

Testing Your Workflow

Once your transition is created, you can test it immediately:

Direct Execution: Call the endpoint via your frontend or curl: POST /api/workflow/exec/counter-demo/increment
State Inspection: Keep the State Inspector open in Mockzilla. You will see the count variable update in real-time as you make calls.
Simulation Mode: Use the Test Transition button in the UI to simulate a request and see exactly which conditions matched and what effects were applied.

Pros & Cons of Stateful Workflows

Pros

End-to-End Simulation: Build and test entire frontend flows (like checkout or multi-step onboarding) without a functioning backend.
Isolated Sandboxes: Scenarios ensure that state changes in one test never leak into another.
Real-Time Forensic Audit: Use the State Inspector to watch your variables and database tables update in real-time as your app interacts with the API.
Mini-DB Persistence: Store and retrieve relational data using simple predicates, making your mocks feel "alive."

Cons

Configuration Overhead: Complex transitions require more setup time compared to simple static mocks.
In-Memory Volatility: Scenario state is stored in memory; restarting the server resets all databases to their initial seed state.
Debugging Complexity: Extremely deep logic chains in JSON can become harder to trace than standard application code.

Ready for more?

Now that you know the basics, dive into one of our full-scale tutorials to see how these concepts build real-world systems.