Beverage Availability Graph

Overview

The Beverage Availability Graph is a specialized diagnostic tool in KOS Studio designed for beverage dispenser systems. When a particular beverage or recipe becomes unavailable on a device, understanding why can be complex, availability depends on multiple interconnected factors including physical holders, ingredient levels, recipe definitions, synonyms, and beverage configurations. The Beverage Availability Graph provides a visual representation of all these dependencies, making it easy to trace why a beverage is unavailable and identify what needs to be addressed.

This tool is particularly valuable for troubleshooting beverage availability issues on dispensing devices, understanding brandset schemas, and making informed decisions about device configuration and inventory management.

Understanding Beverage Availability

In KOS beverage dispensing systems, availability is determined by a hierarchy of interconnected elements called a brandset schema. Understanding these elements and their relationships is key to diagnosing availability issues.

Brandset Schemas

A brandset schema defines all the possible ways beverages can be configured and made available on a device. A single image may have multiple brandset schemas, each representing a different configuration or setup. The Beverage Availability Graph allows you to view and analyze each schema to understand its specific configuration.

Important: Freestyle Brandsets use a different architecture and cannot be viewed in the Beverage Availability Graph. If your image uses Freestyle Brandsets, the tool will inform you that they cannot be displayed.

Schema Elements (Node Types)

A brandset schema consists of several types of nodes, each representing a different aspect of beverage availability:

Holders
Physical locations or positions on the device where ingredients are placed. Holders are the foundation of availability—if a holder is unavailable, beverages requiring ingredients from that holder cannot be poured.

Ingredients
The actual contents or substances that go into beverages. Ingredients are assigned to holders.

Synonyms
Alternative ingredient mappings identified by ingredient ID. Synonyms allow recipes to use different ingredients interchangeably, providing flexibility when specific ingredients are unavailable.

Recipes
Formulas that define how to combine ingredients to create beverages. Recipes are identified by recipe ID and specify which ingredients are needed and in what quantities.

Beverages
The final products that customers can pour, identified by beverage ID. Each beverage links to one or more recipes that can be used to make it.

Node Relationships and Correlation

The power of the Beverage Availability Graph lies in visualizing how these nodes connect:

  • Beverages depend on recipes
  • Recipes depend on ingredients
  • Ingredients depend on holders
  • Synonyms provide alternative ingredient options

When you trace these relationships backward from an unavailable beverage, you can identify exactly which holder, ingredient, or configuration is causing the unavailability.

Accessing the Beverage Availability Graph

Opening the Tool

  1. Log into KOS Studio
  2. In the Connection Manager window, locate your running image (connected to a simulator or device)
  3. Ensure the image is in a Connected state
  4. Find the Active Tools section for that connection
  5. Click + Start New Tool
  6. Select Beverage Availability Graph from the dropdown menu

Note: The Beverage Availability Graph is only available for active connections.

Viewing Brandset Schemas

Initial View

When you first open the Beverage Availability Graph, you’ll see one of several possible states:

No Brandset Deployed:
If the image doesn’t have a brandset deployed, you’ll see a message informing you that no brandset schemas are available for this image.

Freestyle Brandset:
If the image uses Freestyle Brandsets, you’ll see a message explaining that Freestyle Brandsets cannot be viewed by the tool.

Available Schemas:
If the image has one or more brandset schemas configured, you’ll see a view displaying all available schemas to choose from.

Selecting a Schema

If multiple schemas are available:

  1. Review the list of available schemas
  2. Click on the schema you want to analyze
  3. The schema details view opens, showing the complete structure

Each schema represents a different configuration, so you may need to check multiple schemas when diagnosing availability issues across different setups.

Understanding Schema Details

Visual Layout

When you open a schema, the details view displays all node types organized in columns:

Column Organization:

  • Each node type appears in its own column
  • Holders (if present in the schema)
  • Ingredients (if present in the schema)
  • Synonyms (if present in the schema)
  • Recipes (if present in the schema)
  • Beverages (if present in the schema)

Note: Not all schemas include all node types. If a schema doesn’t use a particular node type (such as holders or synonyms), that column won’t appear.

Node Display

Holders Column:
Each holder is represented by its name, showing all physical positions where ingredients can be placed.

Ingredients Column:
Each ingredient is represented by its name, showing all available ingredients in the schema.

Synonyms Column:
Each synonym is represented by its ingredient ID, showing alternative ingredient mappings.

Recipes Column:
Each recipe is represented by its recipe ID, showing all formulas available for making beverages.

Beverages Column:
Each beverage is represented by its beverage ID, showing all final products that can be ordered.

Understanding Node States

The schema includes visual indicators for node availability:

Legend:
A legend appears on the screen explaining the different node states:

  • Not Available: The node is present but currently unavailable (e.g., empty holder, no ingredient assigned)
  • Not Visible: The node is configured but not currently visible or accessible

These states help you quickly identify which nodes are causing availability issues.

Visualizing Relationships

Viewing Correlations

The Beverage Availability Graph draws connections between related nodes, making dependencies visible:

Connection Lines:
Lines connect nodes that have relationships, such as:

  • A beverage connected to the recipes that can make it
  • A recipe connected to the ingredients it requires
  • Ingredients connected to the holders they occupy

No Correlation:
If nodes don’t have relationships to other nodes, no connection lines are drawn to those nodes.

Hover State

To explore relationships interactively:

  1. Hover over any node in the schema
  2. All nodes related to the hovered node are highlighted
  3. Other nodes dim or remain unhighlighted
  4. This makes it easy to trace the dependency chain

Nodes with No Correlations:
If you hover over a node that doesn’t correlate to other nodes, no other nodes are highlighted. In some cases, you may be able to open that node in a separate window for more details.

Selected State

For focused analysis of a specific node:

  1. Click on a node in the schema
  2. The view updates to show only nodes related to the selected node
  3. Unrelated nodes disappear from the screen
  4. You see just the selected node and its correlation chain

Benefits:

  • Focus on a specific beverage and trace back through its recipe, ingredients, and holders
  • Identify exactly which element in the chain is causing unavailability
  • Eliminate visual clutter from unrelated nodes

Single Node:
If you select a node that doesn’t correlate to other nodes, you’ll see only that node in the view.

Navigation

Returning to Schema List

To view other schemas or return to the home screen:

  1. Use the navigation controls to return to the schema selection screen
  2. You can quickly switch between schemas to compare configurations
  3. This is helpful when diagnosing issues across multiple brandset setups

Opening Schema Details

To analyze a specific schema:

  1. Select the schema from the list
  2. The schema details view opens automatically
  3. You can navigate back and forth between schemas as needed

Viewing Node Details

When analyzing correlations:

  1. Select a node to focus on its relationships
  2. The view adjusts to show only relevant nodes
  3. Navigate back to the full schema view to see all nodes again
  4. You can select different nodes to explore different dependency chains

Troubleshooting with Beverage Availability Graph

Diagnosing Unavailable Beverages

When a beverage is reported as unavailable:

  1. Open the Beverage Availability Graph
  2. Select the appropriate brandset schema
  3. Locate the beverage node (identified by beverage ID)
  4. Check if the beverage node shows as “Not Available” or “Not Visible”
  5. Click on the beverage node to see only its related nodes
  6. Trace back through the correlation:
    • Which recipes can make this beverage?
    • Are those recipes available?
    • Which ingredients do the recipes need?
    • Are those ingredients available?
    • Which holders contain those ingredients?
    • Are those holders available?
  7. Identify the first “Not Available” node in the chain—this is your root cause

Understanding Recipe Issues

When recipes aren’t working as expected:

  1. Select the recipe node in the schema
  2. View which ingredients the recipe requires
  3. Check if any required ingredients are unavailable
  4. Trace those ingredients back to their holders
  5. Verify holder status and ingredient levels
  6. Check if synonym alternatives exist for unavailable ingredients

Analyzing Ingredient Problems

When ingredient availability is questionable:

  1. Locate the ingredient node in the schema
  2. Click to see which recipes depend on this ingredient
  3. See which beverages will be affected if this ingredient becomes unavailable
  4. Check the holder assignment for this ingredient
  5. Determine if synonyms can substitute for this ingredient

Identifying Holder Configuration Issues

When holders seem misconfigured:

  1. View all holders in the schema
  2. Check which ingredients are assigned to each holder
  3. Trace forward to see which recipes use ingredients from a specific holder
  4. Identify which beverages will be impacted by holder unavailability
  5. Use this information to prioritize holder refills or repairs

Comparing Multiple Schemas

When working with multiple brandset schemas:

  1. Open the first schema and analyze its structure
  2. Navigate back to the schema list
  3. Open the second schema
  4. Compare node types, relationships, and availability
  5. Identify differences in configuration that might explain behavior variations

Connection Footer

The Beverage Availability Graph displays a connection footer that helps you identify which device or simulator the tool is connected to which includes Image Name, Target Name or IP address and device connection status.

Tips for Effective Use

  • Start with the beverage: When diagnosing unavailability, begin at the beverage level and work backward through the dependency chain
  • Use hover for exploration: Hover over nodes to quickly understand relationships without changing the view
  • Use selection for focus: Click nodes to eliminate visual clutter and focus on specific dependency chains
  • Check node states carefully: Pay attention to “Not Available” and “Not Visible” indicators in the legend
  • Compare schemas: If issues occur in only certain modes or configurations, compare schemas to identify differences
  • Trace to the root cause: Follow the correlation chain back to the first unavailable node—this is typically where you need to take action
  • Document findings: Use the visual representation to document and communicate complex availability issues to team members
  • Verify holder assignments: Many availability issues trace back to incorrect or empty holder assignments
  • Look for synonym opportunities: If an ingredient is unavailable, check if synonyms can provide alternatives
  • Consider the complete chain: Remember that a beverage can be unavailable due to issues at any level—holder, ingredient, recipe, or beverage configuration