GUBUS ROUTE

💡

Use ROUTE for conditional workflow branching when you need to send different objects to different flows based on their field values.

General Route logic

[For each object in localObjs]
  → Extract scan_field_in_obj value
  → Match against root_values (comma-separated list)
  → If match: Route to next_ref target.
    → if target_type is "schema" → new SCHEMA is executed. 
      This schema can have further ROUTING/BATCH/SEQUENTIAL SCHEMA chaining
    → if target_type is "workfeed" or "multipanel" → object is posted 
      directly to the specified PATTERN without SCHEMA involvement
  → If no match: loose, land to last `defined default` route or break execution according to setup

Jump to specific routing methods:

Route by field in object - Static value matching for immutable route sets
Route by field existence - Polymorphic routing based on field presence
Route by presence in rule values - Dynamic routing using external rules
Route by presence in side objs - Runtime routing from loaded data
Default routing - Catch-all routing for unmatched objects

Route by field in object

Routes objects by matching the value in scan_field_in_obj against a comma-separated list in root_values.

Use this type of routing for static route cases, where ruling set is concise and immutable in time.

Configuration Example:

[
  {
    // Route products with category "electronics" to electronics schema
    "reference": "productRouter",
    "scan_field_in_obj": "category",        // Field to check in each object
    "root_values": "electronics,computers", // Values that trigger this route
    "target_type": "schema",
    "next_ref": "processElectronics"
  },
  {
    // Route products with category "clothing" to clothing schema
    "reference": "productRouter",
    "scan_field_in_obj": "category",
    "root_values": "clothing,shoes",
    "target_type": "schema",
    "next_ref": "processClothing"
  },
  {
    // Default route catches all unmatched products
    "reference": "productRouter",
    "route_type": "default_route",          // Catches objects that don't match above
    "target_type": "schema",
    "next_ref": "processOther"
  }
]

Input Data:

[
  { "product": "Laptop", "category": "electronics" },
  { "product": "T-shirt", "category": "clothing" },
  { "product": "Book", "category": "media" }
]

Output Routing:

Laptop → routed to processElectronics (matches “electronics”)
T-shirt → routed to processClothing (matches “clothing”)
Book → routed to processOther (caught by default_route)

Route by presence in rule values

(Dynamic Rule-Based Matching)

Routes objects by checking if the value in scan_field_in_obj exists in a dynamically loaded rule from admin page.

Instead of hardcoding values in root_values, this option fetches values from a rule table using source_ref and from_field_name.

Rule can be updated with new values in other schemas, that enables flexible dynamic routing.

Configuration Example:

[
  {
    // Route orders to VIP processing if customer is in VIP customers rule
    "reference": "orderRouter",
    "route_type": "presence_in_rule_values",  // Enable rule-based routing
    "scan_field_in_obj": "customer_id",       // Field in order object to check
    "source_ref": "vip_customers_rule",       // Rule reference to fetch values from
    "from_field_name": "customer_id",         // Field in rule to extract values from
    "target_type": "schema",
    "next_ref": "processVipOrder"
  },
  {
    // Route orders to regular processing if customer is in regular customers rule
    "reference": "orderRouter",
    "route_type": "presence_in_rule_values",
    "scan_field_in_obj": "customer_id",
    "source_ref": "regular_customers_rule",
    "from_field_name": "customer_id",
    "target_type": "schema",
    "next_ref": "processRegularOrder"
  },
  {
    // Default route for unknown customers
    "reference": "orderRouter",
    "route_type": "default_route",
    "target_type": "schema",
    "next_ref": "processNewCustomerOrder"
  }
]

Rule Data in vip_customers_rule:

[
  { "customer_id": "C001", "tier": "gold" },
  { "customer_id": "C005", "tier": "platinum" },
  { "customer_id": "C012", "tier": "gold" }
]

(System builds Set: [“C001”, “C005”, “C012”])

Input Data:

[
  { "order_id": "O100", "customer_id": "C001", "amount": 500 },
  { "order_id": "O101", "customer_id": "C999", "amount": 50 },
  { "order_id": "O102", "customer_id": "C005", "amount": 1200 }
]

Output Routing:

O100 → routed to processVipOrder (C001 found in vip_customers_rule)
O101 → routed to processNewCustomerOrder (C999 not in any rule, caught by default)
O102 → routed to processVipOrder (C005 found in vip_customers_rule)

Key Benefits:

No hardcoding of customer IDs in schema
VIP list managed in spreadsheet/rule
Updates to VIP list immediately affect routing
Supports dynamic business rules

Route by presence in side objs

(totally dynamic routing)

Routes objects by checking if the value in scan_field_in_obj exists in side objects loaded during schema execution. Side objects are loaded from previous READ operations or other schemas in the same workflow. This is the most flexible routing option - values are determined at runtime from live data.

This flow is exactly the same, but you should configure source_ref as a name of previous SCHEMA to retrieve side objects from.

Route by field existsence

Routes objects based on whether a field exists (and is truthy), not by its value. First matching field wins - useful for polymorphic objects where different fields indicate different types.

Use case: After some split instruction (f.i. distraction_split) in GUBUS there are two new objects with different fields instantiated. Route by field exists is exactly the case to hold.sence of specific fields indicates type (e.g., tracking_number for shipments, invoice_id for invoices).

Configuration Example:

[
  {
    // Route objects with tracking_number to shipment processing
    "reference": "documentRouter",
    "route_type": "field_exists",             // Check field existence, not value
    "scan_field_in_obj": "tracking_number",   // If this field exists → route here
    "target_type": "schema",
    "next_ref": "processShipment"
  },
  {
    // Route objects with invoice_id to invoice processing
    "reference": "documentRouter",
    "route_type": "field_exists",
    "scan_field_in_obj": "invoice_id",        // If this field exists → route here
    "target_type": "schema",
    "next_ref": "processInvoice"
  },
  {
    // Route objects with booking_ref to booking processing
    "reference": "documentRouter",
    "route_type": "field_exists",
    "scan_field_in_obj": "booking_ref",
    "target_type": "schema",
    "next_ref": "processBooking"
  },
  {
    // Default route for objects with none of the above fields
    "reference": "documentRouter",
    "route_type": "default_route",
    "target_type": "schema",
    "next_ref": "processUnknownDocument"
  }
]

Input Data:

[
  { "id": "D001", "tracking_number": "TRK123", "carrier": "DHL" },
  { "id": "D002", "invoice_id": "INV456", "amount": 1500 },
  { "id": "D003", "booking_ref": "BK789", "hotel": "Plaza" },
  { "id": "D004", "note": "Some unstructured data" }
]

Output Routing:

D001 → routed to processShipment (has tracking_number field)
D002 → routed to processInvoice (has invoice_id field)
D003 → routed to processBooking (has booking_ref field)
D004 → routed to processUnknownDocument (no recognized fields, caught by default)

Important Notes:

Field must be truthy (not null, undefined, false, 0, or "")
First rule with existing field wins (order matters!)
Value of field doesn’t matter, only its presence
Common pattern for polymorphic data structures

Default routing

Default routing acts as a safety net - it catches all objects that don’t match any specific routing rules. This prevents objects from being lost and ensures every piece of data has a destination, even if it’s unexpected or doesn’t fit predefined patterns.

Key Characteristics:

Always evaluated last (after all other route rules)
No matching conditions - catches everything that falls through
Essential for robust data processing workflows
Can route to cleanup, error handling, or general processing schemas

Configuration Example:

[
  {
    // Specific routes for known cases
    "reference": "documentProcessor",
    "scan_field_in_obj": "document_type",
    "root_values": "invoice,receipt",
    "target_type": "schema",
    "next_ref": "processFinancialDocs"
  },
  {
    // Default route catches everything else
    "reference": "documentProcessor",
    "route_type": "default_route",           // No conditions - catches all unmatched
    "target_type": "schema",
    "next_ref": "processUnknownDocs"         // Handle unexpected document types
  }
]

Input Data:

[
  { "id": "D001", "document_type": "invoice" },     
  { "id": "D003", "document_type": "photo" },       
  { "id": "D004", "document_type": "memo" }         
]

Output Routing:

D001 → processFinancialDocs (matches “invoice”)
D003 → processUnknownDocs (no match, caught by default)
D004 → processUnknownDocs (no match, caught by default)

Common Default Route Strategies:

Error Handling Route:

{
  "route_type": "default_route",
  "target_type": "schema", 
  "next_ref": "logAndRejectUnknown"
}

Manual Review Route:

{
  "route_type": "default_route",
  "target_type": "workfeed",
  "next_ref": "manualReviewQueue"
}

General Processing Route:

{
  "route_type": "default_route",
  "target_type": "schema",
  "next_ref": "processGenericData"
}

💡

You MAY NOT to place default route at all, if you’re sure that other objects MAY be lost. Hard to imagine that, but things happen, you know.

Route Type Comparison

Route Type	Checks	Use When	Configuration
field_in_object	Value matches list	Known set of values to route	`root_values: "val1,val2,val3"`
presence_in_rule_values	Value exists in external rule	Values change dynamically	`source_ref` + `from_field_name`
presence_in_side_objs	Value exists in side objects	Values determined at runtime	`source_ref` as previous SCHEMA
field_exists	Field is present	Polymorphic objects	`route_type: "field_exists"`
default_route	Catch-all	Unmatched objects	`route_type: "default_route"`

Rule Properties

PROPERTY

DESCRIPTION

reference

Required. Links route rules together. Example: “orderRouter”

scan_field_in_obj

Required. Field to check. Example: “order_type”

root_values

Comma-separated values to match. Example: “wholesale,retail,export”

target_type

Required. “schema”, “workfeed”, or “multipanel”

next_ref

Required. Target reference. Example: “processWholesale”

break_on_false_routing

Boolean. Abort execution if object doesn’t match any route

log_lost_objects

Boolean. Log unmatched objects for debugging

Summary

ROUTE replaces with expressive pattern the need to execute redundant filter on transform if you configured BATCH/SEQUENTIAL flow

✅ Value-based branching logic
✅ Multiple target types (schema/workfeed/multipanel)
✅ Error handling with break/log options

When to use: Multi-pipeline workflows, department routing, priority distribution, serving multiple storages in single run

Next Steps

👉 GUBUS SCHEMA → - Learn how schemas orchestrate workflows 👉 GUBUS WORKFEED → - Learn about permanent data storage 👉 ← Back to Getting Started - Return to the main documentation

General Route logic

Route Types Quick Navigation

Route by field in object

Route by presence in rule values

Route by presence in side objs

Route by field existsence

Default routing

Route Type Comparison

Rule Properties

Summary

Next Steps