GUBUS SCHEMA

GUBUS SCHEMA defines execution mechanics on a top abstraction level, being an orchestration core of GUBUS.

Simply saying, GUBUS SCHEMA contains only references to GUBUS modules that should be triggered on READ → TRANSFORM → POST stages, laconically shapingl execution flow you need.

Each SCHEMA is a self-contained unit that READS data from a source, transforms it according to rules mentioned on TRANSFORM stage, and POSTS the results to one or more destinations, or doesn’t if POST is not intended.

Each SCHEMA has 3 ways to connect next SCHEMA in current execution flow: SEQUENTIAL, BATCH and ROUTE.

One execution SCHEMA flow has its SCHEMA CONTEXT, that enables insane flexibility shaped in primitive flat spreadsheet format.

Table of Contents

Schema Context

There is nothing specially interesting in Schema Context. Exact mechanichs is not exposed due to no-code interface of GUBUS, but you should be aware of its basics.

SCHEMA CONTEXT is the runtime execution state container:

  • Runtime execution state - Holds data and state during execution
  • Data accumulation - Accumulates read and post actions
  • Locking mechanism - Handles mutex to prevent simultaneous executions, this is why GUBUS intended to be a project for small teams
  • Execution logic - Orchestrates reading/postings via GS REST API, outer API integrations and exposure logic (email, SMS, team informing)
  • Local objects - Holds local objects array as main data carrier during schema execution
  • Side objects - Holds side-objs as results of each inner schema execution to provide seamless data proliferations
  • Main message - Holds mainMessage string that is built progressively during schema execution to be shown to user and team
  • Error tracking - Accumulates errors and performance metrics, exposes to user on schema end

Schema Rule Structure

READ Stage Properties:

  • source_type: string - Where to read data from (workfeed, multipanel, side_obj, api_integration, etc.)
  • source_reference: string - Reference name for the source
  • after_read_instuction - so important that we decided to move it on SCHEMA level. Manages main message composition.

After Read Instruction Configuration

PROPERTY
DESCRIPTION
after_read_instruction
Actions after READ stage. Examples: set_main_message, join_main_message_new_line, instant_tg_inform_team

After Read Instructions:

The after_read_instruction property controls actions that happen immediately after the READ stage, before transforms. These instructions can manipulate mainMessage or send instant notifications:

  • set_main_message - Replaces sc.mainMessage with sc.localMessage
  • join_main_message_new_line - Appends sc.localMessage to sc.mainMessage with newline (\n)
  • join_main_message_empty_line - Appends sc.localMessage to sc.mainMessage with empty line (\n\n)

TRANSFORM Stage Properties:

  • function_[number] (up to 10 transforms in one schema allowed) - Transform module names, is defined via GS Data Validation to avoid mistypes, one value allowed at a time
  • function_[number]_args - Holds references to module properties, multiple comma separated values allowed

POST Stage Properties:

  • target_type: string - defines target where to lead data (workfeed, multipanel, route_by_*, gmail, BATCH_connection, RULE etc.)
  • target_names: string - Target references (comma-separated)

Flow Control Properties:

  • next_schema: string - Sequential next schema
  • exec_instruction: string - This field manages For HEAD SCHEMA leave it empty if you want regular execution happen, or show only for debug reasons.
  • ignore_false_results: boolean - Continue execution despite false result or emtpy local object array

Notification Properties:

  • inform_instruction: string - How to expose schema execution (team, user_started, gmail, instant_*, switch_tg_inform_off)
  • inform_args: string - References to corresponding notification properties, depending on istruction choosed

Schema Execution Lifecycle

Initialization Phase

Stage 1: READ

Routes to appropriate reader based on source_type:

  • WORKFEED → WorkfeedReaderCentralService
  • MULTIPANEL → PanelReaderCentralService
  • MOSAIC → InputsReaderCentralService
  • SIDE_OBJ OR SIDE_OBJ_CLONE → Retrieve local objs from SCHEMA CONTEXT. Reference here is the name of previous SCHEMA.
  • *_API_INTEGRATION → ApiIntegrationsService
  • my_api_endpoint - is triggered via outer call to GUBUS API, reference leads to settings to expose api_endpoint, configure hand shake pass and auth method there
  • init_empty_obj_in_arr - for automations, where blank obj needed, to fill with auto generated values in TRANSFORM
  • `sheet_as_pdf’ - places target sheet as pdf to SCHEMA LOCAL CONTEXT, to be proceeded for exposures via email, telegram bot and so on
💡

If nothing is configured for read stage - local objects will be implicitly inherited from previous SCHEMA via reference. !!Important!! It mutates side_obj of that previous SCHEMA!!!

Stage 2: TRANSFORM

Executes transforms sequentially (function_one → function_ten). Each transform modifies sc.localObjs.

Available transform types:

  • validate - Data validation
  • compose - Message construction
  • join - Join with side objects or rules
  • filter - Filter objects
  • transform - Field transformations, including date generations, context variables set, and more
  • reduce - Aggregate data
  • sort - Sort objects
  • index - Reshape arrays to objects
  • split - Split fields
  • merge - Merge objects
  • consume - Consume from side objects

Stage 3: POST

Routes to appropriate POST GUBUS module based on target_type:

  • WORKFEED → Post to workfeed pattern
  • MULTIPANEL → Set back to multipanel
  • ROUTE_BY_* → Route to different schemas/patterns (described in GUBUS ROUTE)
  • BATCH_SCHEMAS' - blindly executes batch of next schemas, defined comma separated in target_names` property.
  • GMAIL → Send email
  • TURBO_SMS - native seamless integration for sms service provider.
  • TOUCH_FLEX_WORKFLOW → Trigger workflow
  • *_API_INTEGRATION - executes get/post api calls whenewher you need.
  • RULE → Update rule in database and on admin page simultaneously

Stage 4: Side Effects

  • Stores result in sc.sideObjs[schemaName]
  • Executes instant inform_instruction if configured
  • Follows next_schema if configured
  • Executes routing if target_type includes route_by_ or ‘batch’ (see GUBUS ROUTE documentation)

Divine Recursion:

Process continues for [next_schema/routed/batch] schemas till it reaches last stop.

Empty local objs array leads to SCHEMA FADING, process where no further transform and post in current schema happen, but execution flow is passed to next_schema silently.

Each schema execution follows the same READ → TRANSFORM → POST pattern.

Inner schema nesting in BATCH or ROUTE schemas is allowed, yes, you can use another one ROUTE/BATCH in inner schema. And yes, you can use next_schema in any inner ROUTE/BATCH schema.

And yes, GUBUS has built-in safety check for circular schemas!

Execution Instructions

If not set defaults to standart schema execution. Better not to change it at all.

  • execute_all_pending (default) - Execute all accumulated requests
  • show_only - Don’t execute, just return results
  • stop_on_empty_local_objs - Stop if no data happened and you know that triggering next schemas is no needed at all.
  • ignore_false_results - Continue execution on false results anyway to next routing

Notification Configuration

Involve inform_instruction specifically for head schema and leave it unconfigured in inner schemas. Manages schema exposure logic.

Some schema executions should be public and seen by all team. Some executions (money, yeah) better to expose via bot personally.

PROPERTY
DESCRIPTION
inform_instruction
Notification type. Examples: inform_tg_team, inform_tg_user_started, instant_tg_inform_team
inform_args
Notification args (Gmail template ref, workspace roles, custom group names)

Inform Instructions:

Configure inform instruction specifically for head SCHEMA unless you precisely know what you’re doing.

The inform_instruction property controls how and when schema execution results are communicated to users. These instructions are executed at the end of schema execution (after all schemas finish) unless prefixed with instant_:

  • inform_tg_team - Notify team group via Telegram at end of execution
  • inform_tg_team_with_pdf - Notify team with PDF attachment
  • inform_tg_user_started - Notify only the user who started this execution (relevant for Workspaces projects)
  • inform_tg_user_started_with_pdf - Notify user with PDF attachment
  • inform_tg_roles - Notify users with specific workspace roles (args: comma-separated role names)
  • inform_custom_tg_groups - Notify custom Telegram groups (args: comma-separated group references)
  • instant_tg_inform_team - Notify team immediately during schema execution (not waiting for end)
  • instant_tg_inform_roles - Notify roles immediately during schema execution
  • switch_tg_inform_off - Disable notifications in initial schema

Schema main message

SchemaContext.mainMessage: string is the accumulated message that will be shown to users and teams:

How it’s built:

  1. In after_read_instruction:
    • set_main_message - Set from localMessage generated on READ stage
    • join_main_message_new_line - Append from localMessage
    • join_main_message_empty_line - Append from localMessage with empty line
  2. In compose transform - via destination_type:
    • set_main_message - Replace mainMessage
    • join_main_message_new_line - Append with \n
    • join_main_message_empty_line - Append with \n\n
  3. In transform transform - via message property:
    • If transform has message, it’s appended via sc.appendToMainMessage()
  4. In other transforms - via message properties:
    • reduce, split, merge, compare, index, join can all append messages

Schema local objects

Each head/inner schema execution operates with local objects array.

** SchemaContext.localObjs: object[] ** is the main data carrier during schema execution.

Local objects could be newly instantiated in current schema, inherited from previous via reference or cloned.

  • Populated by READ stage
  • Modified by TRANSFORM stage
  • Used by POST stage
  • SAVED to side_objs array in SchemaContext
  • Silently inherited in next schema execution if READ stage is not configured

Example:

// After READ from multipanel
sc.localObjs = [
  {order_no: "001", customer: "John", total: 100},
  {order_no: "002", customer: "Jane", total: 200}
]

// After TRANSFORM (join with customers)
sc.localObjs = [
  {order_no: "001", customer: "John",
   total: 100, email: "john@example.com"},
  {order_no: "002", customer: "Jane",
   total: 200, email: "jane@example.com"}
]

// After current schema ends
// new reference in side objects generated, local objs saved there

Schema side objects

SchemaContext.sideObjs: {[schemaName: string]: {result, objs, message}} stores named result sets with result: boolean flag and local message as message

  • Persist across all inner schema executions
  • Retrieved via source_type: side_obj or source_type: side_obj_clone setting source_reference to [schema name]
  • Also stores results from multiple workfeed reads by workfeed reference as name

Example:

// After schema "fetchCustomers" completes
sc.sideObjs['fetchCustomers'] = {
  result: true,
  objs: [
    {id: 1, name: "John"},
    {id: 2, name: "Jane"}
  ],
  message: "2 customers fetched"
}

SchemaContext.side_objs['fetchCustomers']

Advanced Features

Error Handling & Debugging

GUBUS Schema has two kinds of errors:

  1. Critical Errors - Prevent schema execution (e.g., schema not found, circular reference, strict join failures). Schema execution is totally aborted.
  2. Non-Critical Errors - Accumulated in sc.errorMessages, but execution continues. At end of schema execution they will be displayed to user and team.

Debug Mode

💡

Go to admin_server page on gubus admin table, and fill GUBUS DEBUG panel to receive detailed logs posted on gubus_debug sheet.

Behavior:

  • Disables clean/resolve operations
  • Posts intermediate results to debug sheet in admin table
  • Exposes READ results
  • Exposes TRANSFORM results
  • Exposes POST model
  • Can isolate specific transform and output only its result
  • Shows to you whole data flow

Performance Tracking

Set performance_inform_dev in inform_instruction on head schema, and you’ll receive a proper performance report of each schema execution including:

  • Total execution time
  • Rules gathering time
  • Data pools gathering time
  • Each schema execution time
  • Transform execution times

Workflow Integration

This advanced feature is described in GUBUS WORKFLOW documentation.

Workflow is a special GUBUS core that rules item posting, elimination, and update over watched workfeeds and FlexItems, whose state is persisted in the database. Orders, bookings, production items - all can be managed with workflow.

Integration:

  • Triggered via target_type: touch_flex_workflow
  • Requires FlexWorkflowDriverSet
  • Requires positions tracking
  • Triggers via event emitter after execution

Components:

  • MainStatusDriver - Main item states
  • StagesDriverResolver - Stage-specific drivers
  • Tracker - Position and state tracking

Wait for official docs about it soon.

Custom Workfeeds

Purpose: Extend base workfeed with custom properties

  • During preparation, generates new read reference to be used in checker. Want to read present workfeed in another way? Wrap it in custom_workfeed rule!
  • Merges basic_workfeed_ref properties with custom properties, validator and composer
  • Custom workfeed seamlessly integrated in SCHEMA engine, no explicit declaration for it needed, just use conventional ‘workfeed’ name

FreeBusyDay Module

FreeBusyDay is a special module that works out day-based calendar activities, and is used where some actor (room, worker) is booked for the whole day on some date. Currently in implementation.

Relevant for building projects, pensions, hotels, and similar businesses.

WORKSPACES

This feature solves the problem of personal workspaces, where posting should be routed to.

When Needed:

  • User-specific data isolation
  • Different users see different sheets
  • MOSAIC patterns with local flag

How It Works:

  1. SchemaContext has userEmail or userTgUid set
  2. Workspaces rules loaded: sc.rulesPool.workspaces
  3. For each pattern rule, resolves table_id and sheet_id from workspace
  4. Different users = different sheets

Common Pitfalls ⚠️

“Schema rule not found”

  • Cause: You’ve mistyped schema name due to manual input. Always use built-in Data Validations to input schema names!
  • Solution: Verify schema exists in admin sheet

“Transform reference not found for ref X”

  • Cause: Transform reference doesn’t exist or not saved
  • Solution: You’ve mistyped transform name due to manual input. Always use built-in Data Validations to input transform names!

“Pattern rule not found for ref X”

  • Cause: Pattern reference doesn’t exist or not saved
  • Solution: You’ve mistyped pattern name due to manual input. Always use built-in Data Validations to input pattern names!

“Main result falsified”

  • Cause: Error in READ, TRANSFORM, or POST stage
  • Solution: Check sc.errorMessages for details

“Circular reference detected”

  • Cause: Schema calls itself without protection
  • Solution: Add exec_args: "not_circullar" if intentional

Empty localObjs but expected data

  • Cause: Read stage failed or returned no results
  • Solution: Check pattern configuration, stop conditions, data availability

Schema Examples

Example 1: Simple Read-Transform-Post

Schema: processOrders
├─ READ stage
│  └─ source_type: multipanel
│     source_reference: orderInputPanel
│
├─ TRANSFORM stage
│  └─ function_one: transform
│     function_one_args: generateMissingDataAndCalculatedNewFromPresent
│  └─ function_one: join
│     function_one_args: joinCashFlowCategories
│
└─ POST stage
|  └─ target_type: workfeed
|     target_names: orderHistoryFeed
└─ POST stage
|  └─ target_type: workfeed
|     target_names: finOpsFeed

Use Case: User inputs orders in panel → validate → save to orders feed → save financial projection to feed CashFlow happens from

Example 2: Sequential Schema Chain

Schema: orderWorkflow
├─ READ: orderInputPanel
├─ TRANSFORM: validateOrders,
│             calculateTotals
├─ POST: orderHistoryFeed
└─ next_schema: sendOrderNotification

Schema: sendOrderNotification
├─ READ: 
│  (inherits from previous silently)
├─ TRANSFORM: composeEmailMessage
└─ POST: gmail (send notification)

Use Case: Process orders then send notification

Example 3: Routing Pattern

Schema: routeOrders
├─ READ: ordersFeed
├─ TRANSFORM: validateStatus
└─ POST: route_by_field_in_objs

Router: routeOrders
├─ scan_field_in_obj: order_status
├─ Route 1: "pending"
│  → schema: processNewOrders
├─ Route 2: "paid"
│  → schema: shipOrders
└─ Route 3: "completed"
   → workfeed: archivedOrders

Use Case: Route orders to different schemas based on status

Example 4: Multiple Workfeed Read

Schema: consolidateFeeds
├─ READ stage
│  └─ source_type: workfeed
│     source_reference: feed1, feed2, feed3
│
├─ (No transforms allowed
│   - different models)
│
└─ Creates side_objs:
   feed1, feed2, feed3

Schema: processFeed1
├─ READ: side_obj
│  (source_reference: feed1)
├─ TRANSFORM: join_data_from_feed1_to_feed2
└─ POST: metricsFeed

Use Case: Read multiple feeds to undo input posting

Example 5: API Integration

Schema: fetchExternalData
├─ READ stage
│  └─ source_type:
│     get_api_integration_with_transform
│     source_reference: externalApiCall
│
├─ TRANSFORM: enrichData,
│             validateExternal
│
└─ POST: externalDataFeed

Use Case: Call external API, transform, save to feed

FAQ

WHEN SHOULD I USE SIDE_OBJ VS SIDE_OBJ_CLONE? +

Use side_obj when you want to mutate the original data (transforms will modify the source). Use side_obj_clone when you need to preserve the original data for later schemas (creates immutable copy).

CAN I POST TO MULTIPLE WORKFEEDS IN ONE SCHEMA? +

Yes! Use comma-separated target_names: "feed1, feed2, feed3". Make sure your sc.localObjs structure matches the model of ALL target workfeeds. SchemaContext will correctly hold all postings.

Summary

GUBUS Schema System is the backbone of your GUBUS project. Every data flow, every transformation, every business rule is orchestrated through schemas. Understanding the READ → TRANSFORM → POST pattern, mastering SchemaContext data flow, and learning the configuration options will enable you to build complex, maintainable business logic without writing code.

Key Takeaways:

  • Declarative Configuration - Define what you want, not how to do it
  • Three-Stage Pattern - READ → TRANSFORM → POST for all data flows
  • Schema Composition - Chain schemas sequentially or route conditionally
  • Side Objects - Share data between schemas efficiently
  • Main Message - Build user-friendly output progressively
  • Error Handling - Critical errors abort, non-critical errors accumulate
  • Debug Mode - Test schemas safely without affecting production
  • Integration - Seamlessly works with patterns, transforms, workflow, freeBusyDay module, api integrations and bots

Start with simple schemas, test with debug mode, and gradually build more complex orchestrations as you gain confidence.

Next Steps

👉 Back to GUBUS RULE → - Learn about GUBUS rule structure 👉 Continue to GUBUS MULTIPANEL → - Learn about input patterns 👉 Continue to GUBUS WORKFEED → - Learn about storage patterns 👉 ← Back to Getting Started - Return to the main documentation