---
url: /services/workflow/air-traffic-tutorial.md
description: >-
  End-to-end BPMN workflow tutorial solving an air traffic graph-coloring
  problem by orchestrating quantum services on Kipu Quantum Hub.
---

# Building an Air Traffic Management Workflow with Quantum Computing

## Overview

Welcome to this comprehensive tutorial on creating BPMN workflows for the Platform platform!
You'll learn workflow fundamentals while building a complete quantum application that solves a real-world optimization problem:
**air traffic management**.

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

* Understand BPMN basics and workflow concepts
* Use the visual workflow modeler effectively
* Design both sequential and parallel service execution
* Implement proper data flow between services
* Create production-ready quantum workflows
* Test and debug complex workflows

### The Problem We're Solving

When multiple flight routes intersect, a flight authority must assign each flight to different air corridors to prevent collisions.
This is a complex optimization problem that becomes computationally expensive as the number of flights increases.

Mathematically, we can represent this problem as a so-called graph-coloring problem, where each flight route is a node and intersecting routes are connected by edges.
This is a well-known NP-hard problem in computer science.
We can leverage quantum computing to optimize air corridor assignments efficiently.
For a more detailed explanation of the underlying optimization problem, see our [Air Traffic Management Use Case](https://dashboard.hub.kipu-quantum.com/use-cases/bd58ec9f-42ef-4ec7-bd79-86afb85dad97).

We use the following running example throughout the tutorial:
Consider the following five flight routes between European cities:

* HEL → FCO (Helsinki to Rome)
* BER → MAD (Berlin to Madrid)
* CDG → OTP (Paris to Bucharest)
* FCO → CDG (Rome to Paris)
* OTP → OSL (Bucharest to Oslo)

On a map, these routes look like this:
![Flight Route Visualization](./problem-visualization.jpeg "Map showing five flight routes between European cities, used as input for the air traffic optimization workflow.")

Given these flight routes, we have several intersections:

* HEL → FCO intersects with
  * OTP → OSL
  * CDG → OTP
* BER → MAD intersects with
  * FCO → CDG
  * CDG → OTP

Thus, our air traffic management system must:

* Identify which routes intersect
* Use quantum optimization to find non-conflicting corridors for intersecting routes
* Generate visual maps showing the corridor assignments

### What You'll Build

An air traffic management system that:

1. **Encodes** flight routes into a quantum optimization problem
2. **Solves** the problem using quantum computing (Illay Base Quantum Optimizer service)
3. **Decodes** the quantum solution back to flight corridor assignments
4. **Visualizes** both the problem and solution on generated maps
5. **Runs in parallel** to generate the problem visualization while solving the quantum problem

### Why Use Workflows?

Workflows solve a key challenge in quantum computing: orchestrating complex, multi-step 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

## Part 0: Understanding BPMN Basics

Before diving into workflow creation, let's understand the fundamentals of [BPMN](https://bpmn.org/) (Business Process Model and Notation).

### What is BPMN?

BPMN is a standardized visual language for modeling business processes.
Within 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         |
| **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] → ●
```

This workflow executes three services one after another in sequence.

### Example: Parallel Execution Workflow

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

This workflow generates a circuit once, then executes it on two different backends simultaneously. The parallel gateway (◇+) splits the flow, and another parallel gateway synchronizes the results.

### Understanding the Workflow Modeler Interface

When you create a workflow service on our platform, you'll work with the visual workflow modeler.
Here are its main components:

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

#### The Canvas (Center)

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

#### The Palette (Left Side)

* Contains all BPMN elements you can use
* **Common elements** are visible by default:
  * Platform Service Task (▢)
  * Parallel Gateway (◇+)
  * Exclusive Gateway (◇×)
  * End Event (●)
* Click **"..."** for advanced elements (loops, conditional flows, boundary events)

#### The Properties Panel (Right Side)

* Displays configuration options for the selected element
* **Click on any element** to see its properties here
* Use it to:
  * Configure service subscriptions
  * Set input/output data mappings
  * Define API parameters
  * Add error handling
  * Set timeouts

### How Data Flows in Workflows: Workflow Variables and Data Mapping

Each service in your workflow can:

* **Receive input data** from previous steps (or from the workflow input)
* **Produce output data** for following steps
* **Access workflow variables** defined anywhere in the workflow

You can use variables to store and pass data between services.
This includes input parameters, service outputs, and intermediate results.
All variables are stored in a shared context accessible by all workflow tasks.
As a result, you can define an input parameter at the Start Event and use it in any subsequent service.
Similarly, outputs from one service can be stored as variables and used later.

Variables are defined in two ways:

1. *At the Start Event, i.e., as input parameters*: Define input parameters in the "API Description" section of the Start Event.
   This enables the modeler to recognize the parameters as workflow variables.

   For example, consider you want to have two input parameters and define the following at the API description of the Start Event:

   ```json
   {
     "flightRoutes": [
       {
         "origin": "HEL",
         "destination": "FCO"
       }
     ],
     "mapOutput": {
        "ref": "datapool",
        "id": "uuid-of-your-datapool"
     }
   }
   ```

   Within the workflow, these inputs become available as variables with name `flightRoutes` and
   `mapOutput` that can be used throughout the workflow.

2. *From Service Tasks:* Store service outputs into output variables.
   Our modeler supports the API description of a service.
   Thus, you can see what outputs are available to store as variables.
   You can even select a nested object from a service's output to store as a variable.

   For example, consider a service with output like this:

   ```json
   {
     "result": {
       "id": "12345",
       "status": "completed"
     },
     "execution_time": 120
   }
   ```

   Then you can store the entire `result` object as a variable or just the `id` field by specifying `result.id`.

We'll see concrete examples of this later in the tutorial.
For more information, see our [Data Manipulation in Workflows](./data-manipulation.md) guide.

::: warning Heads-up
You won't see the **Workflow** tab until **Part 2** when you create the Workflow Service.
:::

## Part 1: Understanding the Workflow Architecture

### Workflow Overview

```
○ → [Encode Routes] → ◇+ → [Solve with Illay] → [Decode Solution] → ◇+ → [Visualize Solution] → ●
                       └ → [Visualize Problem] -------------------→ ┘
```

### Services

#### 1. AirSpace Encoder

The AirSpace Encoder service converts flight routes into a quantum optimization problem.
It analyzes which routes intersect and creates a quantum problem where the goal is to minimize conflicts by assigning routes to different corridors.

##### Input

```json
{
  "flight_routes": [
    {
      "origin": "HEL",
      "destination": "FCO"
    },
    {
      "origin": "BER",
      "destination": "MAD"
    }
  ]
}
```

##### Output

* `coefficients`: Mathematical representation of the optimization problem
* `airports`: List of airports with coordinates (for visualization)
* `route_mapping`: Mapping between flight routes and quantum qubits

#### 2. Illay Base Quantum Optimizer Service

The Kipu Illay Base Quantum Optimizer service solves a quantum optimization problem.
In this case, the one encoded by the AirSpace Encoder.
To achieve that, it executes a quantum algorithm to find the optimal corridor assignments that minimize conflicts.

##### Input

* `problem`: The problem from the encoder
* `problem_type`: "binary" (each route is assigned yes/no to each corridor)
* `shots`: Number of quantum circuit executions (higher = more accurate)
* `num_greedy_passes`: Optimization iterations

##### Output

* `result`: Quantum solution
* `result.mapped_solution`: Best solution found

#### 3. AirSpace Decoder

The AirSpace Decoder converts the quantum solution back to human-readable format.

##### Input

* `solution`: The quantum result from Illay
* `routes`: The quantum mapping from the encoder

##### Output

* `channels`: List of corridors with their assigned routes.

For example:

```json
[
  {
    "channel": "Corridor 0",
    "routes": [
      {
        "origin": "HEL",
        "destination": "FCO"
      }
    ]
  },
  {
    "channel": "Corridor 1",
    "routes": [
      {
        "origin": "CDG",
        "destination": "OTP"
      },
      {
        "origin": "FCO",
        "destination": "CDG"
      }
    ]
  }
]
```

#### 4. Air Traffic Visualizer

The Air Traffic Visualizer creates visual maps of flight routes and corridor assignments.

##### Input

* `channels`: Corridor assignments from decoder (or custom structure for problem visualization)
* `airports`: Airport coordinates from encoder
* `file_output_dir`: Datapool location to store the image
* `filename`: Name for the generated visualization

##### Output

Saves an interactive map visualization to the specified datapool

## Part 2: Creating the Workflow Service

### Prerequisites

Before starting this tutorial, you should:

* Be familiar with basic quantum computing concepts
* Have a new [application](https://dashboard.hub.kipu-quantum.com/applications) created for our new workflow service
* **Name your application** anything you prefer (e.g., `air-traffic-demo`). Consistent naming helps when selecting services later.
* Have subscriptions to the following Kipu services within the application:
  * [Illay Base Quantum Optimizer](https://hub.kipu-quantum.com/marketplace/services/4e7919d4-7509-455c-ba28-3614fad695ff)
    You can create a free subscription to this service using our marketplace.
    Simply navigate to "Pricing & Subscription" and click "Subscribe".
    **Subscribe to Illay within the same application** you'll use for this workflow **before** opening the Workflow Modeler.
* Create three new services from our public implementation:
  1. Click each implementation link below:
     * [AirSpace Encoder](https://dashboard.hub.kipu-quantum.com/community/implementations/74b1be35-b5b5-4b92-bf11-d2466650fe1e) - Converts flight routes to quantum problems
     * [AirSpace Decoder](https://dashboard.hub.kipu-quantum.com/community/implementations/0ca68e6d-06aa-4d24-86ec-e30922ca7faa) - Converts quantum solutions to corridor assignments
     * [Air Traffic Visualizer](https://dashboard.hub.kipu-quantum.com/community/implementations/07edb294-374b-441c-9adf-9565c661b9a0) - Generates map visualizations
  2. **Click "Create Service" first** on the top right inside each implementation, then return here for the next steps
* **Publish internally:** Open each service → **Publish** → \*\*Internal
  \*\*. You should see them on the top of your [list of services](https://dashboard.hub.kipu-quantum.com/services).
* Subscribe to each AirSpace service within your application:
  1. Navigate to your [application's subscriptions page](https://dashboard.hub.kipu-quantum.com/applications)
  2. Click "Subscribe Internally"
  3. In the dropdown, select each AirSpace service and click "Subscribe"

::: warning Important
Make sure to subscribe to all the services within an application. \*\*Use Personal context
\*\* for this tutorial; other contexts (e.g., "Kipu Quantum") may cause errors.
:::

::: tip
Use the same application for all services.
You can subscribe to multiple services within one application as well as have subscriptions to the same service in different applications.
:::

### Naming Conventions Used in This Tutorial

Throughout this tutorial, we use consistent names for each workflow step. Here's a quick reference:

| Logical step         | Standard name                    | Notes                                            |
|----------------------|----------------------------------|--------------------------------------------------|
| Encoder service task | **Encode Flight Routes**         | Converts flight routes to quantum problems       |
| Illay optimizer task | **Solve Quantum Problem**        | Executes quantum optimization                    |
| Decoder service task | **Decode Quantum Solution**      | Converts quantum results to corridor assignments |
| Problem visualizer   | **Visualize Original Problem**   | Shows the input problem visualization            |
| Solution visualizer  | **Visualize Optimized Solution** | Shows the optimized solution visualization       |

### Step 1: Create the Workflow Service

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

2. Select **"Quantum Workflow Service"**

3. Fill in the details:

   | Field       | Value                                                                                                                                                                                                                                                                                       |
   |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | Name        | Air Traffic Management Workflow                                                                                                                                                                                                                                                             |
   | Summary     | Quantum-optimized air corridor assignment for flight routes                                                                                                                                                                                                                                 |
   | Description | This workflow uses quantum computing to assign flight routes to air corridors, minimizing the risk of collisions when routes intersect. It encodes flight routes as a quantum optimization problem, solves it using Illay, and generates visual maps showing both the problem and solution. |

4. Click "Create Service"

### Step 2: Open the Workflow Modeler

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

## Part 3: Building the Workflow Control Flow

:::warning
You can only use services in your workflow to which you have a valid subscription.
Thus, if you developed a service yourself, you must publish it internally and add a subscription to it in an application.
Similarly, for public services, you must have a valid subscription within an application.
:::

We will model a workflow that should look something like this in the end:

![Completed Air Traffic Workflow](./tutorial-final-workflow.png)

### Step 1: Define Workflow Input

First, configure what data your workflow will accept:

1. Select the Start Event or create one (○)
2. In the **properties panel** (right side), navigate to **"API Description"**
3. Add this example request:

```json
{
  "flightRoutes": [
    {
      "origin": "HEL",
      "destination": "FCO"
    },
    {
      "origin": "BER",
      "destination": "MAD"
    },
    {
      "origin": "CDG",
      "destination": "OTP"
    },
    {
      "origin": "FCO",
      "destination": "CDG"
    },
    {
      "origin": "OTP",
      "destination": "OSL"
    }
  ],
  "mapOutput": {
    "ref": "datapool",
    "id": "uuid-of-your-datapool"
  }
}
```

::: tip Understanding the Input

* `flightRoutes`: Array of flight routes to optimize (use [IATA airport codes](https://en.wikipedia.org/wiki/IATA_airport_code))
* `mapOutput`: Datapool reference where visualization images will be saved
  * `ref`: Always "datapool" for platform datapools
  * `id`: Your datapool UUID

**Find your Datapool UUID:** Navigate to **Data → Datapools** in the left navigation, open your datapool, and copy the \*\*UUID
\*\* from the details panel.
:::

### Step 2: Add the AirSpace Encoder

1. **Drag** a **Platform Service Task** from the palette onto the canvas
2. **Connect** the Start Event to this task (click Start Event, drag the arrow)
3. Click the **wrench icon** (🔧) on the task
4. **Select** the **AirSpace Encoder** service from the dropdown
5. In the **General** tab (properties panel), set **Name** to: `Encode Flight Routes`

### Step 3: Create Parallel Gateway for Dual Visualization

After encoding, we want to:

* Solve the quantum problem **AND**
* Visualize the original problem

Both can happen in parallel:

1. **Drag** a **Gateway** (◇) after the encoder task
2. Click on the Gateway and make it a **Parallel Gateway (◇+)** by clicking on the wrench icon
3. **Connect** the encoder task → parallel gateway
4. This gateway will split the flow into two parallel paths

### Step 4: Add Quantum Solving Branch (Top Path)

#### 4.1: Add Illay Base Quantum Optimizer Service

1. **Drag** a **Platform Service Task** above the parallel gateway
2. **Connect** parallel gateway → this task
3. Click **wrench icon** (🔧), select **Illay Base Quantum Optimizer Service**
4. Set **Name** to: `Solve Quantum Problem`

#### 4.2: Add Decoder Service

1. **Drag** another **Platform Service Task** after Illay
2. **Connect** Illay task → this task
3. Click **wrench icon** (🔧), select **AirSpace Decoder**
4. Set **Name** to: `Decode Quantum Solution`

### Step 5: Add Problem Visualization Branch (Bottom Path)

1. **Drag** a **Platform Service Task** below the parallel gateway
2. **Connect** parallel gateway → this task (second branch)
3. Click **wrench icon** (🔧), select **Air Traffic Visualizer**
4. Set **Name** to: `Visualize Original Problem`

### Step 6: Add Synchronization Gateway

Both parallel branches must complete before continuing:

1. **Drag** another **Parallel Gateway** to the right
2. **Connect** the decoder task → this synchronization gateway
3. **Connect** the problem visualizer task → this synchronization gateway

::: tip Gateway Default
When you drag a Gateway from the palette, the default is **Exclusive**. For this tutorial, switch it to \*\*Parallel (◇+)
\*\* by clicking the gateway and selecting the parallel type from the properties panel.
:::

### Step 7: Add Solution Visualization

1. **Drag** a **Platform Service Task** after the synchronization gateway
2. **Connect** synchronization gateway → this task
3. Click **wrench icon** (🔧), select **Air Traffic Visualizer**
4. Set **Name** to: `Visualize Optimized Solution`

### Step 8: Add End Event

1. **Drag** an **End Event** (●) from the palette
2. **Connect** the solution visualizer → end event
3. **Save** your workflow (button in top left)

### Verify Your Control Flow

Your workflow should now look like this:

```
○ → [Encode Flight Routes] → ◇+ → [Solve Quantum Problem] → [Decode Quantum Solution] → ◇+ → [Visualize Optimized Solution] → ●
                             └ -→ [Visualize Original Problem] -----------------------→ ┘
```

Your workflow should look similar to the image above.

:::tip
Make sure to have the green "No issues" indicator at the bottom of the modeler.
If it is grey, simply click on it to activate the model errors.

If there are any issues, you will see a red indicators at the corresponding elements.
:::

::: warning Publishing Note
You **do not need to publish** the newly created \*\*Workflow Service
\*\* itself for this tutorial. Deploying the workflow (covered in Part 5) is sufficient for testing.
:::

## Part 4: Configuring Data Flow

Now that the control flow is complete, configure how data moves between services.

### Step 1: Configure AirSpace Encoder

**Select** the "Encode Flight Routes" platform service task.

#### Inputs Section:

Click **+** to add input mapping:

| Local variable name | Variable assignment value | Description                                |
|---------------------|---------------------------|--------------------------------------------|
| `flight_routes`     | `flightRoutes`            | Array of flight routes from workflow input |

::: tip Why no quotes?
`flightRoutes` (without quotes) references the workflow variable from the Start Event. This directly passes the flight routes array to the encoder service.
:::

#### Outputs Section:

Store the encoder's three outputs as workflow variables.

::: warning Order Matters
In the UI, **Process variable** appears first and **Assignment/Result** second. Follow this order for **all** output mappings.
:::

Click **+** for each output mapping:

| Process variable name | Result variable name | Description                                             |
|-----------------------|----------------------|---------------------------------------------------------|
| `coefficients`        | `quantumProblem`     | Mathematical representation of the optimization problem |
| `airports`            | `airportsInRoutes`   | List of airports with coordinates for visualization     |
| `route_mapping`       | `quantumMapping`     | Mapping between flight routes and quantum qubits        |

### Step 2: Configure Illay Base Quantum Optimizer Service

**Select** the "Solve Quantum Problem" platform service task.

#### Inputs Section:

Click **+** for each input mapping:

| Local variable name | Variable assignment value | Description                                               |
|---------------------|---------------------------|-----------------------------------------------------------|
| `problem`           | `quantumProblem`          | The encoded quantum optimization problem from the encoder |
| `problem_type`      | `"binary"`                | Type of optimization problem (quoted literal string)      |
| `shots`             | `1000`                    | Number of quantum circuit executions for accuracy         |
| `num_greedy_passes` | `0`                       | Number of classical optimization iterations               |

::: warning Using Literal Values
When using literal strings or numbers:

* Strings: Use quotes: `"binary"`
* Numbers: No quotes: `1000`
* Booleans: No quotes: `true` or `false`
  :::

#### Outputs Section:

Click **+** to add output mapping:

| Process variable name    | Result variable name | Description                                  |
|--------------------------|----------------------|----------------------------------------------|
| `result.mapped_solution` | `quantumSolution`    | Best quantum solution found by the optimizer |

### Step 3: Configure AirSpace Decoder

**Select** the "Decode Quantum Solution" platform service task.

#### Inputs Section:

Click **+** for each input mapping:

| Local variable name | Variable assignment value | Description                                         |
|---------------------|---------------------------|-----------------------------------------------------|
| `solution`          | `quantumSolution`         | The quantum solution from Illay optimizer           |
| `routes`            | `quantumMapping.routes`   | Route mapping from the encoder (using dot notation) |

::: tip Accessing Nested Data
`quantumMapping.routes` uses dot notation to access the `routes` property within the `quantumMapping` object. This is standard FEEL expression syntax.
:::

#### Outputs Section:

Click **+** to add output mapping:

| Process variable name | Result variable name | Description                                           |
|-----------------------|----------------------|-------------------------------------------------------|
| `channels`            | `solutionChannels`   | Decoded corridor assignments with routes per corridor |

### Step 4: Configure Problem Visualizer

**Select** the "Visualize Original Problem" platform service task.

#### Inputs Section:

Click **+** for each input mapping:

| Local variable name | Variable assignment value                          | Description                                                |
|---------------------|----------------------------------------------------|------------------------------------------------------------|
| `channels`          | `[{"channel": "Problem", "routes": flightRoutes}]` | Single channel containing all original routes (JSON array) |
| `airports`          | `airportsInRoutes`                                 | Airport coordinates from encoder                           |
| `file_output_dir`   | `{"id": mapOutput.id, "ref": "datapool"}`          | Datapool reference for saving the visualization            |
| `filename`          | `"problem-visualization"`                          | Name for the generated problem map image                   |

::: details Understanding the `channels` Input
The visualizer expects an array of channel objects. For the problem visualization, we create a single channel called "Problem" containing all the original routes:

```json
[
  {
    "channel": "Problem",
    "routes": flightRoutes
  }
]
```

This shows all routes in one color before optimization, helping visualize which routes intersect.
:::

### Step 5: Configure Solution Visualizer

**Select** the "Visualize Optimized Solution" platform service task.

#### Inputs Section:

Click **+** for each input mapping:

| Local variable name | Variable assignment value                 | Description                                                   |
|---------------------|-------------------------------------------|---------------------------------------------------------------|
| `channels`          | `solutionChannels`                        | Decoded corridor assignments from the decoder                 |
| `airports`          | `airportsInRoutes`                        | Airport coordinates from encoder (same as problem visualizer) |
| `file_output_dir`   | `{"id": mapOutput.id, "ref": "datapool"}` | Datapool reference for saving the visualization               |
| `filename`          | `"solution-visualization"`                | Name for the generated solution map image                     |

::: tip Channel Difference
Notice the solution visualizer uses
`solutionChannels` from the decoder, which contains multiple corridors (Corridor 0, Corridor 1, etc.) with optimized route assignments. Each corridor is displayed in a different color, showing the conflict-free solution.
:::

### Save Your Work

Click the **Save** button in the top left of the modeler.

## Part 5: Testing Your Workflow

### Step 0: Define the input schema

Before executing the workflow, define the input schema for better validation and usability.

::: tip Learn More
For a comprehensive explanation of how workflow services automatically generate their API from input schemas, see [Automatic API Generation](/services/workflow/api-generation).
:::

1. Select the **Start Event** (○)
2. In the properties panel, navigate to the **"API Description"** section
3. Paste the following JSON schema in the `Request Schema` field:
   ```json
   {
     "type": "object",
     "properties": {
       "flightRoutes": {
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
             "origin": { "type": "string" },
             "destination": { "type": "string" }
           },
           "required": ["origin", "destination"]
         }
       },
       "mapOutput": {
         "type": "object",
         "properties": {
           "id": {
             "type": "string",
             "format": "uuid"
           },
           "ref": {
             "type": "string",
              "enum": [
                "datapool"
              ]
           }
         },
         "required": ["id", "ref"],
         "additionalProperties": false
       }
     },
     "required": ["flightRoutes", "mapOutput"]
   }
   ```

Based on this schema, the platform will validate your input when executing the workflow via the Service Jobs page.

### Step 1: Deploy the Workflow

1. In your workflow service, navigate to the "Workflow" tab
2. Click "Deploy" in the top left
3. Wait for deployment to complete (green toast will appear in the top right)

::: tip Save → Deploy
After any change in the modeler, click **Save**.
However, your changes will only be available in an execution, if you deployed the workflow.
To deploy it, simply click on **Deploy** before running again.
Deploy also saves the latest changes.
:::

### Step 2: Prepare Your Datapool

1. Navigate to **[Datapools](https://dashboard.hub.kipu-quantum.com/datapools)** (or use **Left nav: Data → Datapools** if the link fails)
2. Create a new datapool (or use an existing one). Name your datapool freely (e.g., `air-traffic-results-01`).
3. **Copy the datapool UUID** from the datapool details page

### Step 3: Execute the Workflow

1. On your workflow service page, click the green "Run Service" button in the top left

   :::tip
   As an alternative, you can navigate to the [Service Jobs](https://dashboard.hub.kipu-quantum.com/service-jobs) page and click on "Create Service Job".
   In the service dropdown, select your workflow service.
   :::

2. **Input Mode:** Use **Manual JSON** and paste the sample below. Replace the datapool UUID.

   In the "Input Mode" section, use this test request (⚠️ Do not forget to replace the datapool ID):

   ```json
   {
     "flightRoutes": [
       {
         "origin": "HEL",
         "destination": "FCO"
       },
       {
         "origin": "BER",
         "destination": "MAD"
       },
       {
         "origin": "CDG",
         "destination": "OTP"
       },
       {
         "origin": "FCO",
         "destination": "CDG"
       },
       {
         "origin": "OTP",
         "destination": "OSL"
       }
     ],
     "mapOutput": {
       "ref": "datapool",
       "id": "YOUR-DATAPOOL-UUID-HERE"
     }
   }
   ```

3. Replace `YOUR-DATAPOOL-UUID-HERE` with your actual datapool UUID

4. Click "Create Job"

5. You'll automatically be redirected to the job details page

### Step 4: Monitor Execution

**Where to find Service Jobs:** Navigate to **Left nav: Operations → Service Jobs**.

1. Navigate to the **"Service Jobs"** tab
2. Find your job in the list (most recent will be at the top)
3. Click on the job to see detailed execution progress
4. Watch as each service task completes:
   * ✅ Encode Flight Routes
   * 🔄 Solve Quantum Problem (this may take 1-2 minutes)
   * 🔄 Visualize Original Problem
   * ✅ Decode Quantum Solution
   * ✅ Visualize Optimized Solution

::: tip Parallel Execution in Action
Notice that "Solve Quantum Problem" and "Visualize Original Problem" run simultaneously. This is parallel processing working as designed!
:::

::: warning Troubleshooting
If your workflow fails, check these common issues:

* Re-check **Part 4** output mappings (Process variable → Result variable order)
* Confirm **Parallel** vs **Exclusive** gateway where indicated
* Ensure **Personal** context (not "Kipu Quantum")
* **Save → Deploy** again, then re-run
* If the **encoder fails**, start with output mapping fixes
  :::

### Step 5: View Results

1. When the workflow completes, navigate to your **datapool**

2. You should see two new files:
   * `problem-visualization.png` - Shows all original routes
   * `solution-visualization.png` - Shows routes organized into optimal corridors

3. If files don't appear immediately, **refresh** the datapool tab.

4. Preview and compare the images:
   * **Problem visualization**: All routes shown together (potential conflicts)
   * **Solution visualization**: Routes colored by corridor assignment (conflict-free)

## Part 6: Understanding the Results

### Reading the Visualizations

#### Problem Visualization

* All flight routes shown in the same color
* You can see where routes intersect (potential collision points)
* This represents the input to the optimization problem

#### Solution Visualization

* Routes colored by corridor assignment
* Different colors = different corridors (vertically separated in real airspace)
* Routes in the same corridor don't intersect
* This represents the optimized solution from quantum computing

### What the Quantum Computer Did

The Illay Base Quantum Optimizer service:

1. Explored many possible corridor assignments
2. Used quantum superposition to evaluate multiple solutions simultaneously
3. Found the assignment that minimizes conflicts
4. Returned the optimal solution

## Part 7: Returning Data from Workflows

By default, your air traffic workflow saves visualization images to the datapool but doesn't return data via the API to external callers. To return corridor assignments and other results programmatically, 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: `corridors` with expression: `solutionChannels`
* Variable name: `quantum_result` with expression: `quantumSolution`
* Variable name: `status` with expression: `"optimization_complete"`

Your API will return:

```json
{
  "corridors": [
    {
      "channel": "Corridor 0",
      "routes": [
        {
          "origin": "HEL",
          "destination": "FCO"
        }
      ]
    },
    {
      "channel": "Corridor 1",
      "routes": [
        {
          "origin": "BER",
          "destination": "MAD"
        }
      ]
    }
  ],
  "quantum_result": [
    1,
    0,
    1,
    0,
    1
  ],
  "status": "optimization_complete"
}
```

This enables external applications to consume the optimization results programmatically, in addition to the visual maps stored in your datapool.

## Part 8: Next Steps

### Extend the Workflow

Now that you have a working air traffic management workflow, try these extensions:

1. **Multi-Objective Optimization**: Add fuel efficiency and delay minimization to the optimization goals

2. **Dynamic Route Updates**: Create a loop that re-optimizes when new flights are added

3. **Weather Integration**: Add a weather service that influences corridor assignments

4. **Real-Time Monitoring**: Connect to a live flight data API for real-world testing

5. **Comparative Analysis**: Run the same problem on multiple quantum backends and compare results

### Share Your Workflow

1. Add comprehensive documentation to your service description
2. Publish the workflow service to the Platform marketplace
3. Create example API calls in the service documentation
4. Share your results with the Platform community

### Learn More

* **[FEEL Expressions Reference](https://docs.camunda.io/docs/components/modeler/feel/what-is-feel/)**: Advanced data transformations
* **[BPMN 2.0 Specification](https://www.omg.org/spec/BPMN/2.0/)**: Complete BPMN reference
* **[Platform API Documentation](https://docs.hub.kipu-quantum.com/)**: Integrate workflows into your applications

## Summary

Congratulations! You've built a production-ready quantum workflow that:

* ✅ Solves a real-world optimization problem
* ✅ Uses quantum computing (Illay) for enhanced performance
* ✅ Implements parallel processing for efficiency
* ✅ Generates visual results for easy interpretation
* ✅ Handles data flow between multiple services

### Key Takeaways

1. **Service Orchestration**: Workflows coordinate multiple services without custom code
2. **Parallel Processing**: Use parallel gateways to execute independent tasks simultaneously
3. **Data Flow**: Map inputs/outputs carefully using FEEL expressions
4. **Quantum Integration**: Illay makes quantum computing accessible through simple APIs
5. **Visualization**: Transform complex results into understandable visual formats

### What You Learned

* Creating complex workflow control flows with parallel branches
* Configuring service task inputs/outputs with nested data structures
* Integrating quantum optimization services
* Testing and debugging workflows
* Best practices for production deployment

***

## Appendix: Quick Reference

### BPMN Elements Cheat Sheet

| Element                   | Symbol           | Purpose                    | When to Use                          |
|---------------------------|------------------|----------------------------|--------------------------------------|
| **Start Event**           | ○                | Workflow entry point       | Every workflow needs exactly one     |
| **End Event**             | ●                | Workflow completion        | Mark successful completion           |
| **Platform Service Task** | ▢                | Execute a service          | Call any subscribed Platform service |
| **Parallel Gateway**      | ◇+               | Split/merge parallel flows | Run tasks simultaneously             |
| **Exclusive Gateway**     | ◇×               | Conditional branching      | Choose one path based on condition   |
| **Sequence Flow**         | →                | Execution order            | Connect all elements                 |
| **Error Boundary Event**  | ⚡ on task border | Handle errors              | Catch service failures               |
| **Timer Boundary Event**  | ⏰ on task border | Handle timeouts            | Prevent hanging tasks                |

### Data Mapping Quick Reference

#### Input Configuration

```
Local variable name: data
Variable assignment value: {
  "field1": workflowVariable,
  "field2": "literal value"
}
```

#### Output Configuration

```
Result variable name: outputVariable
Process variable name: response.field
```

#### FEEL Expression Examples

```javascript
// Variables (no quotes)
variableName
object.property

// Literals (with quotes for strings)
"string value"
123
true

// Arrays and objects
  [1, 2, 3]
{
  "key"
:
  value
}

// Operations
value1 + value2
count(array)
string(number)

// Conditions
value > 10
count(routes) < 5
```

### Resources

**Documentation**:

* [FEEL Expressions](https://docs.camunda.io/docs/components/modeler/feel/what-is-feel/)
* [BPMN 2.0 Specification](https://www.omg.org/spec/BPMN/2.0/)
* [Platform Docs](https://docs.hub.kipu-quantum.com/)

**Services**:

* [Platform Marketplace](https://hub.kipu-quantum.com/marketplace)
* [Service Subscriptions](https://dashboard.hub.kipu-quantum.com/applications)
* [Datapools](https://dashboard.hub.kipu-quantum.com/datapools)