---
url: /services/workflow/introduction.md
description: >-
  Introduction to BPMN workflow fundamentals for orchestrating multi-step
  quantum services visually on Kipu Quantum Hub.
---

# BPMN Workflow Tutorial

Welcome to the complete guide for creating and managing BPMN workflows on the Quantum Hub!
This tutorial will take you from the basics to building complex quantum workflows that orchestrate multiple services.

### What You'll Learn

By the end of this tutorial, you'll be able to:

* Understand BPMN fundamentals and workflow concepts
* Create your first quantum workflow service on the Quantum Hub
* Use the visual workflow modeler effectively
* Design both sequential and parallel service execution
* Implement proper data flow between services
* Create reusable workflow APIs
* Follow best practices for production workflows

### Why Use Workflows?

Workflows solve a key challenge in quantum computing: \*\*orchestrating complex, multistep processes
\*\* without manual programming. Instead of writing Python code to integrate individual platform services, you can:

✅ **Visually design** your process flow using BPMN diagrams\
✅ **Automate service execution** with built-in error handling\
✅ **Handle long-running processes** (hours to weeks) reliably\
✅ **Monitor progress** in real-time\
✅ **Reuse workflows** as standalone platform services\
✅ **Bridge technical and business requirements** for better collaboration

### Prerequisites

Before starting this tutorial:

* Be familiar with basic quantum computing concepts
* Have subscriptions to the platform services you want to orchestrate

If you want to follow the examples in this tutorial, you can subscribe to the following services:

* [MQT Benchmarking](https://hub.kipu-quantum.com/marketplace/services/aa08ae7d-c593-442a-9c8d-f961d5a87b00)
* [IonQ Simulator](https://hub.kipu-quantum.com/marketplace/services/fcb63fad-b09e-4cd7-bc33-58690157e3c9)
* [MQT Simulator](https://hub.kipu-quantum.com/marketplace/services/5b71eb55-7f1f-4f6e-af17-b6d050b26d86)
* [E-Mail Service](https://hub.kipu-quantum.com/marketplace/services/b4697587-f67c-4ea4-ad7f-6dc2145aa5d7)

To subscribe to these services, create a new application on the [platform > applications](https://dashboard.hub.kipu-quantum.com/applications).
You can create subscriptions to the services by selecting your new application when clicking the
`Subscribe` button on the details page of the respective service in the marketplace.

## Part 1: Understanding BPMN Basics

Before diving into workflow creation, let's understand the fundamentals of BPMN (Business Process Model and Notation).

### What is BPMN?

BPMN is a standardized visual language for modeling business processes.
In the platform, we use BPMN 2.0 to define how quantum services should be executed and how data flows between them.

#### Key BPMN Elements for Platform Workflows

| Element                   | Symbol | Icon                                                                                   | Purpose                                                                               |
|---------------------------|--------|----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| **Start Event**           | ○      |         | Marks where your workflow begins                                                      |
| **End Event**             | ●      |           | Marks where your workflow ends and specifies which variables it returns to the caller |
| **Platform Service Task** | ▢      |  | Executes a subscribed platform service                                                |
| **Parallel Gateway**      | ◇+     |       | Splits flow to run tasks in parallel                                                  |
| **Sequence Flow**         | →      | →                                                                                      | Shows the order of execution                                                          |

#### Example: Simple Sequential Workflow

```
○ → [Generate Circuit] → [Execute on Backend] → [Send Results] → ●
```

#### Example: Parallel Execution Workflow

```
○ → [Generate Circuit] → ◇+ → [Backend 1] → ◇ → [Send Results] → ●
                          └ → [Backend 2] → ┘
```

## Part 2: Creating Your First Workflow Service

### Step 1: Create the Service

1. Navigate to the [service creation page](https://dashboard.hub.kipu-quantum.com/services/new)

2. Select **"Create New Service"** and choose **"Quantum Workflow Service"**.

3. Fill in the required information:

   | Property     | Description                                     | Example                                                                                                                                                   |
   |--------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
   | Name         | Choose a meaningful name for your service       | "Quantum Benchmarking Workflow"                                                                                                                           |
   | Service Type | Select "Quantum Workflow Service"               | Quantum Workflow Service                                                                                                                                  |
   | Summary      | Brief description for the marketplace           | "Automated benchmarking across multiple quantum backends"                                                                                                 |
   | Description  | Detailed explanation of what your workflow does | "This workflow generates benchmark circuits, executes them on multiple quantum computing backends in parallel, and sends results via email notification." |

4. Click **"Create Service"** to proceed

### Step 2: Access the Workflow Modeler

1. Click on your newly created workflow service
2. Navigate to the **"Workflow"** tab
3. You'll see the visual workflow modeler with a single **Start Event** (○)

## Part 3: Building Your First Workflow - Practical Example

Let's build a real quantum benchmarking workflow step by step. This workflow will:

1. Generate a benchmarking circuit
2. Execute it on multiple quantum backends in parallel
3. Send results via email when complete

### Understanding the Workflow Modeler Interface

In the following image, you can see the main components of the workflow modeler:

![Workflow Modeler Interface](./workflow_modeler_interface.png)

#### The Canvas

* **Central workspace** where you design your workflow
* Initially shows only a **Start Event** (○)
* **Drag and drop** elements from the palette to build your workflow

#### The Palette (Left Side)

* Contains all BPMN elements you can use
* **Common elements** are visible by default
* Click **"..."** for advanced elements (loops, conditional flows, etc.)

#### Essential Elements for Workflow Creation

* **Platform Service Task** (▢): Calls a subscribed platform service
* **Parallel Gateway** (◇+): Creates parallel execution paths
* **End Event** (●): Marks workflow completion
* **Sequence Flow** (→): Connects elements to show execution order

#### The Properties Panel (Right Side)

* Displays configuration options for the selected element
* Use it to set properties like service names, input/output variables, and more
* Click on any element to see its properties here

### Step-by-Step: Building the Control Flow

#### Step 1: Add Your First Service Task

1. From the **palette**, drag a **Platform Service Task** (▢) onto the canvas
2. Position it to the right of the Start Event
3. **Connect** the Start Event to the task:
   * Click on the **Start Event** (○)
   * Drag the appearing **arrow** to the **Platform Service Task**

#### Step 2: Configure the Service Task

1. Click the **wrench icon** (🔧) on the task
2. In the configuration panel, select the `MQT Benchmarking` service from the dropdown.
   This service will generate a quantum circuit for benchmarking.
3. In the properties panel on the right, select the General tab.
4. Give the task a descriptive name, e.g., "Generate Benchmark Circuit", instead of the default name for more clarity.

#### Step 3: Add Parallel Execution

For running the circuit on multiple backends simultaneously:

1. **Add a Parallel Gateway**:
   * Drag **Parallel Gateway** (◇+) from the palette
   * Place it after your benchmarking task
   * Connect the benchmarking task → parallel gateway

2. **Add Backend Execution Tasks**:
   * Drag two **Platform Service Tasks** for different backends
   * Position them below the parallel gateway
   * Connect the parallel gateway to each task:
     * Click the **parallel gateway**
     * Drag arrows to each task
   * Configure each task to use a different backend service by clicking the wrench icon (🔧) and selecting the appropriate service:
     * For the first task, select `IonQ Simulator Execution Service`
     * For the second task, select `mqt-ddsim` and give it a name like "MQT Simulator"

3. **Add Synchronization Gateway**:
   * Drag another **Parallel Gateway** after the backend tasks
   * Connect both backend tasks to this synchronization gateway
   * This ensures both backends complete before continuing

#### Step 4: Add Final Steps

1. **Add Email Notification**:
   * Drag a **Platform Service Task** after the synchronization gateway
   * Configure it to use an email notification service
   * Name it "Send Results Email"

2. **Add End Event**:
   * Drag an **End Event** (●) from the palette
   * Connect the email task to the end event

3. **Save Your Workflow**:
   * Click the **Save** button in the top left

#### Your Complete Workflow Should Look Like:

```
○ → [Generate Circuit] → ◇+ → [IonQ Simulator] → ◇+ → [Send Email] → ●
                          └ -→ [MQT Execution] → ┘
```

![Control Flow Example](./result-workflow.png)

### Step-by-Step: Implementing Data Flow

Data flow defines how information (like quantum circuits, results, parameters) moves between services in your workflow.

#### Understanding Data Variables

Each service in your workflow can:

* **Receive input data** from previous steps
* **Produce output data** for following steps
* **Access workflow parameters** (like email addresses, benchmark names)

#### Step 1: Define Workflow Input Parameters

When you want your workflow to receive input from external sources (API calls), you must configure the \*\*Start Event
\*\* with a manual request example that defines the expected input structure.
The corresponding OpenAPI specification will be generated automatically based on this configuration.

1. In the workflow modeler, select the Start Event (○)
2. In the properties panel, navigate to the **"API Description"** section
3. Define an example input your workflow will accept
   ```json
   {
     "benchmark_name": "ghz",
     "email_recipient": "your-email@your-company.domain"
   }
   ```

This manual request example serves multiple purposes:

* **Each key in the JSON** corresponds to a workflow variable
* **Documents the API interface** for external systems
* **Provides examples** for testing and integration

The field names from your manual request example become workflow variables that can be referenced directly in service task configurations.
For example, `benchmark_name` and `email_recipient` can be used in subsequent service tasks to pass the data as input.

#### Step 2: Configure Service Task Data Mapping

When you select a service task in your workflow, you need to configure how data flows in and out.
Click the service task to open the properties panel on the right.

![Service Task Data Mapping](./dataflow-input.png)

To provide input and output data for the service task, you can use [FEEL expressions](https://docs.camunda.io/docs/components/modeler/feel/what-is-feel/).

#### Setting Up Input Variables

1. Select the "Generate Benchmark Circuit" service task.
2. **Navigate to the "Inputs" section** in the properties panel.
3. **Add input variables** by clicking the `+` **button**.
4. **Define the "local variable name"**. This is maps to the service's request elements that it expects as input.
   Use the exact names as shown in the API documentation of the service interface.
   You can see the API example values in the **Request Example** panel.
   In the example shown in the figure above, the only expected input of the service is `data` as printed in the Request Example panel.
   Thus, use `data` as the local variable name to provide a value for the service.
5. **Set values** to the variable using JSON format.
   The expected structure is shown in the API documentation and Request Example panel.
   For the MQT Benchmarking service, you could set the value of the `data` variable like this:
   ```json
   {
     "benchmark_name": "qhz",
     "circuit_size": 5
   }
   ```
6. **Use workflow variables** directly (without quotes) when referencing data from previous steps.
   For example, if you have a variable `benchmark_name` from any previous step, you can use it like this:
   ```json
   {
     "benchmark_name": benchmark_name,
     "circuit_size": 5
   }
   ```
   This will automatically set the value from the output variable called
   `benchmark_name` within the workflow into the JSON object when the service is invoked.

The key points:

* **Local variable name**: `data` (as shown in the service's interface documentation)
* **Variable assignment value**: Maps your input variables to the service's expected input.
* **Use the Request Example**: The panel shows a "Request Example" - structure your input mapping to match this format.
* **Variable references**: Use workflow variable names directly (without quotes) when referencing data from previous steps.

#### Setting Up Output Variables

1. **Navigate to the "Outputs" section** in the service task configuration.
2. **Define how to store the service response** in workflow variables.
3. **Use the Response Example**: The panel shows a "Response Example" - this tells you what data structure the service will return.

In the example shown below, the generated circuit from the MQT Benchmarking service is returned in the `qasm` field of the response.
It is stored this in a variable called `Circuit` for use in subsequent tasks.

![Service Task Output Mapping](./dataflow-output.png)

#### Practical Data Mapping Examples

`MQT Benchmarking` Service Configuration
**Inputs section:**

* Local variable name: `data`
* Variable assignment value:

```json
{
  "benchmark_name": benchmark_name,
  "circuit_size": 5
}
```

**Outputs section:**

* Store the service response (QASM circuit) in variable: `quantum_circuit`

`IonQ Execution` Service Configuration\
**Inputs section:**

* Local variable name: `data`
* Variable assignment value:

```json
{
  "circuit": Circuit
}
```

**Outputs section:**

* Store the execution results in variable: `IonqExecutionResult` from the `counts` value of the service's response.

`MQT Simulator` Service Configuration\
**Inputs section:**

* Local variable name: `data` with variable assignment value:
  ```json
  {
    "qc": Circuit
  }
  ```
* Local variable name: `params` with variable assignment value:
  ```json
  {
    "shots": 100
  }
  ```

**Outputs section:**

* Store the execution results in variable: `MqtExecutionResult` from the `result.counts` value of the service's response.

`Email Service` Configuration
**Inputs section:**

* Local variable name: `data` with variable assignment value:
  ```json
  {
  "to": email_recipient,
  "subject": "Benchmark result available",
  "message": "I'm happy to inform you that the backend execution results are available: IonQ: " + string(IonqExecutionResult) + " MQT DDSIM " + string(MqtExecutionResult)
  }
  ```

**Key Tips:**

* ✅ **Always check the Request/Response Examples** in the service task configuration
* ✅ **Match the exact JSON structure** shown in the Request Example
* ✅ **Use workflow variables** (like `benchmark`, `email_recipient`) in your mappings
* ✅ **Store service outputs** in descriptive variable names for use by later tasks
* ❌ **Don't guess the data format** - always refer to the provided examples

#### Step 3: Returning Data from Workflows

By default, workflow services do not return any data via the API to external callers.
To return data, configure output variables on the **End Event**:

1. Select the End Event (●) in your workflow
2. Navigate to the "Outputs" section in the properties panel
3. Add output variables using [FEEL expressions](./data-manipulation.md)

The output variables become fields in your workflow's API response. For example, if you configure:

* Variable name: `ionq_result` with expression: `IonqExecutionResult`
* Variable name: `mqt_result` with expression: `MqtExecutionResult`
* Variable name: `status` with literal expression: `"completed"`

Your API will return:

```json
{
  "ionq_result": {"00": 45, "11": 55},
  "mqt_result": {"00": 42, "11": 58},
  "status": "completed"
}
```

#### Advanced Data Flow Patterns

##### Conditional Data Flow

Use **Exclusive Gateways** (◇×) to route data based on conditions:

```
[Check Results] → ◇× → [Success Path] (if results valid)
                   └→ [Error Path] (if results invalid)
```

### Creating a Reusable Service API

Transform your workflow into a reusable service that others can integrate:

#### Step 1: Define Service Interface

In the **"API Description"** section of your workflow, create a meaningful example input.
Currently, no schema is supported but only the example request.

#### Step 2: Implement Error Handling

Add **Error Boundary Events** to handle service failures gracefully:

1. **Service Timeout**: Add timer boundary events to tasks
2. **Service Errors**: Add error boundary events with retry logic
3. **Notification**: Always notify users of both success and failure cases

## Part 4: Best Practices & Advanced Patterns

### Workflow Design Best Practices

#### 1. Keep It Simple

✅ **Do**: Start with simple sequential workflows\
✅ **Do**: Add complexity gradually as needed\
❌ **Avoid**: Over-engineering with unnecessary parallel paths

#### 2. Handle Errors Gracefully

✅ **Do**: Add timeout boundaries to long-running tasks\
✅ **Do**: Implement retry logic for critical services\
✅ **Do**: Always notify users of failures\
❌ **Avoid**: Silent failures or infinite loops

#### 3. Design for Monitoring

✅ **Do**: Use descriptive task names\
✅ **Do**: Add intermediate checkpoints for long workflows\
✅ **Do**: Log important intermediate results\
❌ **Avoid**: Black-box workflows without visibility

#### 4. Optimize for Performance

✅ **Do**: Use parallel execution for independent tasks\
✅ **Do**: Minimize data transformations between services\
✅ **Do**: Cache expensive computations when possible\
❌ **Avoid**: Unnecessary sequential bottlenecks

### Common Workflow Patterns

#### Pattern 1: Fan-Out/Fan-In (Parallel Processing)

```
○ → [Prepare Data] → ◇+ → [Process A] → ◇+ → [Combine Results] → ●
                      └ → [Process B] → ┘
```

**Use when**: Processing the same data with multiple services

#### Pattern 2: Pipeline (Sequential Processing)

```
○ → [Step 1] → [Step 2] → [Step 3] → [Step 4] → ●
```

**Use when**: Each step depends on the previous step's output

#### Pattern 3: Conditional Flow

```
○ → [Check Condition] → ◇× → [Path A] → ●
                         └→ [Path B] → ●
```

**Use when**: Different actions needed based on data or conditions

#### Pattern 4: Error Handling with Compensation

```
○ → [Main Task] → [Success Action] → ●
    │
    └→ [Error Handler] → [Cleanup] → ●
```

**Use when**: You need to clean up after failures

### Troubleshooting Common Issues

#### Issue: "Service Not Found"

**Symptoms**: Workflow fails with service subscription error\
**Solutions**:

1. Verify you have an active subscription to the service
2. Check service name spelling in task configuration
3. Ensure service is still available in the marketplace

#### Issue: "Data Mapping Error"

**Symptoms**: Service receives wrong data format\
**Solutions**:

1. Check input/output variable names match exactly
2. Verify data types match service requirements
3. Add data transformation script if needed

#### Issue: "Workflow Timeout"

**Symptoms**: Workflow stops without completion\
**Solutions**:

1. Check individual service timeouts
2. Add timer boundary events to long-running tasks
3. Implement progress checkpoints

#### Issue: "Parallel Tasks Don't Synchronize"

**Symptoms**: Some parallel branches complete but others hang\
**Solutions**:

1. Ensure all parallel paths have proper error handling
2. Add timeout boundaries to parallel tasks
3. Check for data dependency conflicts

### Testing Your Workflows

#### 1. Start Simple

* Test individual service tasks first
* Use minimal test data initially
* Verify each step completes successfully

#### 2. Test Error Scenarios

* Simulate service failures
* Test timeout conditions
* Verify error notifications work

#### 3. Performance Testing

* Test with realistic data sizes
* Monitor execution times
* Check resource usage

#### 4. Integration Testing

* Test the complete end-to-end flow
* Verify all data mappings work correctly
* Test with real user scenarios

### Production Deployment Checklist

Before publishing your workflow service:

#### ✅ Functionality

* \[ ] All service tasks configured correctly
* \[ ] Data flow works end-to-end
* \[ ] Error handling implemented
* \[ ] User notifications working

#### ✅ Documentation

* \[ ] Service description clear and accurate
* \[ ] API parameters documented
* \[ ] Expected outputs defined
* \[ ] Usage examples provided

#### ✅ Performance

* \[ ] Reasonable execution timeouts set
* \[ ] Parallel execution used where beneficial
* \[ ] Resource usage optimized

#### ✅ Reliability

* \[ ] Error handling tested
* \[ ] Retry logic implemented
* \[ ] Monitoring and logging configured

### Advanced Features

#### Looping and Iteration

Use **Loop Characteristics** on tasks to repeat operations:

* **Standard Loop**: Repeat a fixed number of times
* **Multi-Instance**: Process array data in parallel
* **Sequential Multi-Instance**: Process array data one by one

#### Conditional Logic

Use **Exclusive Gateways** (◇×) with conditions:

```javascript
// Example condition: Check if fidelity is acceptable
$
{ionq_results.fidelity > 0.95}
```

#### Event-Driven Workflows

Use **Message Events** to trigger workflows from external systems:

* **Message Start Event**: Start workflow from API call
* **Message Intermediate Event**: Wait for external notification
* **Timer Events**: Schedule periodic executions

#### Sub-Processes

Break complex workflows into reusable sub-processes:

* **Embedded Sub-Process**: Inline complex logic
* **Call Activity**: Reuse other workflow definitions

### Next Steps

Now that you understand BPMN workflows on the Quantum Hub, it's time to start building your own!:

1. **Practice**: Build simple workflows with your subscribed services
2. **Experiment**: Try different patterns (parallel, conditional, loops)
3. **Share**: Publish useful workflows for the community
4. **Learn More**: Explore advanced BPMN features as needed

### Resources

* [BPMN 2.0 Specification](https://www.omg.org/spec/BPMN/2.0/)
* [Service Marketplace](https://dashboard.hub.kipu-quantum.com/marketplace)
* [Community Support Forum (Discord)](https://discord.gg/qhwDBPpuFE)