1. Papers
  2. Stubber Paper

Papers

Stubber Paper

Overview of the Stubber Framework

This paper outlines the key concepts of the Stubber Framework. The Stubber Framework is a structured method for defining any organizational process. Here, the term "process" is used broadly, encompassing anything that can be automated or collaborated on. The framework aims to enhance organizational efficiencies and foster better collaboration.

The Stubber Framework serves as the foundation for the Stubber Platform, an online platform that implements these concepts and ideas. The Stubber Platform can be accessed at app.stubber.com. What sets the Stubber Framework apart is its emphasis on clarity and flexibility.

The Stubber Framework

The Stubber Framework is a formal framework based on the concept of a finite state machine (FSM), where an object can be in only one of a set of finite states. The Stubber Framework goes beyond a typical FSM by providing detailed definitions of the actions that transition between states. States and actions are the two most important components of the Stubber Framework.

The framework allows us to map any real-world process into a structure that represents that reality. It provides a method for conceptualizing processes and transforming the complexities of the real world into a more manageable form. Additionally, the framework must facilitate the execution of processes within the Stubber Platform. A common framework enables:

  • diverse people and organizations to have a common understanding of how to work together
  • artificial intelligence to understand processes better
  • executable processes on a platform
  • fast iteration of processes
  • versioning and history of changes
  • separation of concerns
  • experimentation by branching

Part A - Template and Stub

  • The template and stub make up the highest level of abstraction in the framework.

  • The template is used for defining.

  • The stub is used for execution.

  • A stub is a single instance of a template.

  • A stub is a manifestation of a template.

  • There is a one to many relationship between template and stubs.

  • One template has many stubs.

  • One stub has only a single template.

In other words, many stubs can share the same template. For example, if we have a template called "Sales Enquiry," then for each interested customer, we will create a "Sales Enquiry" stub. We can say we have 100 "Sales Enquiry" stubs. Similarly, if we have a template called "Employee Onboarding," then for each employee we onboard into the organization, we will create an "Employee Onboarding" stub. Therefore, we have 50 "Employee Onboarding" stubs.

Section A.1 Template

A process template or just template is the top level structure which contains the definition of the process.
A template is something that represents a process or concept that could occur in the real world.
A template is named in the singular.
A template is the fundamental definition abstraction in the framework.

Naming

When working with the framework the first thing to define is the template name.
The template name should make sense when prefixed with the following sentences :
"We have 100 [template_name] stubs in the system"
"Jack was working a [template_name] stub"

Good template names should be descriptive and contain multiple words to ensure clarity when an organization defines many templates. For example, if we have "Sales Enquiry" and multiple diverse needs for "Sales Enquiry," it would be better to call them "General Sales Enquiry" and "Enterprise Sales Enquiry" if they represent sufficiently different processes.

Formal Naming Standard

  • singular
  • lowercase
  • uses underscore for spaces

Example Template Names

  • sales_lead
  • general_enquiry
  • vehicle_service
  • website_customer_chat_conversation
  • expense_claim
  • support_assistant_conversation

Section A.2 Stub

A stub is the workhorse of the Stubber Framework.
A stub always has a specific template that it follows.
A stub represents an instance of a process occurring / running in the real world.
A stub is the fundamental execution abstraction in the framework.
A stub has a subject that gives is a short human name.
A stub has a stubref which is a globally unique identifier with a set format.

Stubref Introduction

A stubref is a globally unique identifier. This allows the stubref to be used across multiple organizations as a single reference to a specific instance of a process (template). Using a stubref ensures that you don't have to use opaque references like "The Sales Enquiry for Customer A," "The Order Number X23," or "The onboarding for employee Jack."

A stubref gives you the ability to uniquely identify the single stub that contains all the information for the specific template. It solves many instances of confusion in organizations where there are many differing reference standards and references from multiple systems. Additionally, using a stubref simplifies referencing across multiple organizations.

Stubref Format

YYYY-MM-DD-XXXX-YYYY

  • YYYY represents the year the stub was created
  • MM represents the month the stub was created
  • DD represents the day the stub was created
  • XXXX is reserved for future and is set as literal "XXXX"
  • YYYY is a random alphanumeric code generated by the platform

Examples of stubrefs

  • 2023-05-17-XXXX-WERN
  • 2024-01-01-XXXX-NEWY
  • 2025-01-01-XXXX-ABCD

Stub Detailed Concept

A stub is intended to be a single source of truth for a specific instance of any template in the framework.
The stub is central to the Stubber Platform as it is the how processes are executed and run on a daily basis.
The stub allows people, systems and artificial intelligence to share a common context.
The stub contains a log of all changes to the state of the stub and all data, people and files associated with it.
A stub is the fundamental unit in the framework that also gives the framework its name "Stubber"

Part B - Template Structure

A template is the most important part of the framework because it contains all the defining information for the process.

A template has a set structure that allows the platform to execute the template in the form of a stub for each real-world instance.

Section B.1 Template Structure Overview

The template structure consists of multiple parts that provide different functionalities.

Branches

The template is first divided into branches.
A branch represents different "versions" of the template to allow experimentation and iteration of the template.
The 2 default branches are draft and live.
The draft branch is used to build the template and test functionality before copying to the live branch which represents the version that is used in the live platform.
Having a draft and live branch allows changes to be tested before deploying to the larger organization.

Contexts

Each template branch is further divided into contexts.
A context represents different viewpoints onto the template.
Contexts allow separating the differing high-level functions of a template.
The best way to explain contexts is explain each of the standard contexts.

Standard Contexts
create context

The create context contains the definition of how to create new stubs of this template.
For example you could use the create context to define that an email gets sent out each time a new stub of the "Sales Enquiry" template gets created.

default context

The default context contains the definition of the actual process flow for the template.
For example if you created a new "Sales Enquiry" stub the process that each "Sales Enquiry" would follow is defined here, so in this example it might contain actions allowing the user to "collect customer details" or "send_quote".

manage context

The manage context contains the definition of the process to manage all the stubs of the template together.
For example you could use the manage context to define actions that would close all the open stubs or generate a report for all the open stubs.
Any actions that would apply to all the stubs of a specific template are defined in the manage context.

Advanced usage for contexts

You could define your own contexts to run A/B testing for example. You could use contexts to define a default_a and default_b context and then on the create context you could randomly assign a different "default* context to each stub.

Parts

Each context consists of 2 parts namely a flow and a layout.

Flow

A flow is the most important part of each context where the states and actions are defined.
Most of the work done on templates will be on the flow.
The flows contain the real working definitions in any template.
The flow definition structure is defined later in this document as its own part.

Layout

A layout is where the visual layout of a stub is defined. The Stubber Platform will use the layout to display the actual stub.

Section B.2 Template Structure Summary

In summary the template structure will follow a structure similar to this :

  • template :
    • branch :
      • context :
        • flow :
        • layout :

Example of higher level structure

  • sales_enquiry :
    • draft :
      • default :
        • flow : [default flow]
        • layout : [default layout]
      • create :
        • flow : [create flow]
        • layout : [create layout]
      • manage :
        • flow : [manage flow]
        • layout : [manage layout]
    • live :
      • default :
        • flow : [default flow]
        • layout : [default layout]
      • create :
        • flow : [create flow]
        • layout : [create layout]
      • manage :
        • flow : [manage flow]
        • layout : [manage layout]

Part C - Flow Structure

Flows are such an important part of the Stubber Framework that the definition is split out from the overall structure.
In this part we focus on the definition of all the components that make up a flow.

Section C.1 Basic Flow

A flow consists of 2 main components states and actions.
A state represents a finite state that the a stub can be in.
A action defines fields, tasks,notifications,metrics and transitions to other states.

Each action can have an optional to_state which defines the state it will transition the stub to when run.
Each state has one or many actions that are available in that state.

Let's go into more detail.

Subsection C.1.1 - States

A state represents a significant period of time in the process. Each individual stub can only be in one state at any given time. The state should provide a clear indication of how far the process has progressed. Thus, naming the states well is very important. The state should be named in a way that allows people, systems, and artificial intelligence to quickly ascertain the real-world state. The state also dictates which actions are available to be run on the stub. For example, you might have a state called "customer-details-pending" and an action called "capture_customer_details".

Formal State Naming Standard
  • singular
  • lowercase
  • uses dashes for spaces
Naming States

Naming states well is important.
The naming of the state can reflect certain aspects of the process such as :

  • that the process is waiting for some event
  • that some work is in progress and the process is awaiting its completion
  • simple aspects like active

Good names for a state always follow these rules :

  • Can either start with or end with certain phrases
  • Can start with one of these phrases :
    • "waiting-for"
    • "awaiting"
  • Can end with one of these phrases :
    • "in-progress"
    • "pending"
    • "active"
Final and Reserved States

There are certain state names that are reserved for use in the framework.
pending is a reserved state that is used on initialization of a new stub before setting its busy start_state.
_done* is a final state that represents the stub being complete.

State Sentence Test

If you have named your state well you should be able to test if the following sentences make sense.
You should be able to prefix "The stub is in [state]". For example "The stub is in cost-authorization-pending".
You should be able to say "[state] is the current state of the stub". For example "awaiting-approval is the current state of the stub".

State Name Examples

Examples of good state names :

  • waiting-for-customer-contact
  • awaiting-customer-details
  • awaiting-conversation-start
  • customer-contact-pending
  • details-pending
  • conversation-in-progress
  • repair-in-progress
  • awaiting-customer-authorization
  • awaiting-approval
  • negotiation-in-progress
  • setup-in-progress
  • cost-authorization-pending
  • chat-active
  • installation-active
The Art of state naming

The art of naming the state correctly is crucial and depends on the process. Sometimes, you may want to make the state general and loosely defined, for example, "customer-onboarding-in-progress," which allows for a diverse set of possible actions. At other times, you may want to narrowly define the state, such as "customer-call-pending," "customer-creation-in-progress," or "customer-welcome-email-pending," representing very specific steps in the process.

Subsection C.1.2 - Actions

An action represents a single point in time.
An action represents something happening in the process.
An action can be as general as a comment update on a stub or very specific that it performs some real-world action.
An action is where all of the execution happens in the Stubber Framework.
An action can optionally be used to transition the state of the stub.
An action has 5 main functions: collect data through fields, run tasks, send notifications, record metrics and transition state.
An action is set to available inside a state.

Formal Action Naming Standard
  • singular
  • lowercase
  • uses underscores for spaces
Naming Actions

Naming actions well is important. The name of the action should allow a person, system, or artificial intelligence to easily choose their desired path through the process.

Ideally, an action should begin with a verb and be phrased from the point of view of the person, system, or AI that would be using it on the stub. Care should be taken to name the action in the context of the process and not to confuse it with tasks.

For example, an action might have a task that saves data to a Google Sheet, but the action should reflect the higher-level process. In this example, the action might be capture_customer_data, as it is independent of the task to save to the Google Sheet.

In general, the action naming should not include any technical jargon or words. The action name should be related to the higher-level process and easily understood by the general public

Final and Reserved Actions

There are certain action names that are reserved for use in the framework.
_create is a reserved action that is used to boot up a new stub.
_update is a reserved action that is used as a general comment update action on a stub.

Action Sentence Test

If you have named your action appropriately, you should be able to test its clarity and purpose by checking if the following sentences make sense.

You should be able to prefix the action with "I want to [action]" For example, "I want to authorize_cost."

This means the action name should clearly describe what you intend to do.

You should be able to say "[action] is what Jack did." For example, "approved_quote is what Jack did."

This indicates the action name should be descriptive enough to explain what has already been done.

These tests help ensure your action names are intuitive and meaningful, making your code more readable and understandable.

Action Name Examples

Examples of good action names :

  • authorize_cost
  • approve_loan
  • submit_customer_details
  • complete_job
  • log_equipment_failure
  • start_chat_conversation
  • send_quote
  • capture_customer_information
  • complete_repair
  • submit_new_order

Action main functions

The main 5 functions of an action are :

  1. Collect data through fields
  2. Perform tasks
  3. Send notifications
  4. Record metrics
  5. Transition state

Collecting Data

An action can collect data before being executed.
You can define fields on the action that will be displayed to the user on the Stubber Platform or given to an AI as parameters to submit.
This data collection function happens before execution of the action.

Perform Tasks

An action can perform tasks that allow a huge variety of functionality to be realized.
The Stubber Framework allows for defining tasks as plugins, this enables extensibility.
New functionality can easily be added by building a new Stubber task type.
Each task has parameters that allow injecting data from the stub into the task to execute.

Common task examples are :

  • Call a REST API
  • Create a new stub
  • Set some data on the stub
  • Manipulate data on the stub
  • Set the stub subject
  • Send an action to another stub
  • Interact with a LLM artificial intelligence
  • Save data into a Google Sheet
  • Generate a PDF file from a document template
  • Emit an event on the Heimdall global event system
  • Register for an event on the Heimdall global event system

Using a task on a stub is a great way to make the process action real-world actions. This allows the process to be executed in the real world and save time and work.

There is a rich library of task types in the Stubber Platform that allow the user to implement various functionality.

The tasks are run by the platform when an action gets submitted along with the optional data collected through fields.
The tasks are run in sequential order as defined on the action.

Send Notifications

An action can send notifications to keep people, systems, and artificial intelligence updated. The Stubber Framework allows for defining notifications as plugins, enabling extensibility. New notification platforms can easily be added by building a new Stubber notification type. Each notification has parameters that allow injecting data from the stub into the notification, enriching the message. Each notification needs to specify the contacts to whom the notification is to be sent.

Common notification examples are :

  • Send an email
  • Send an email with file attachment
  • Send a Whatsapp message
  • Send a SMS
  • Send a Slack message to a channel
  • Send a Teams message
  • Initiate a call to a number
  • Send a location pin on Whatsapp

The notification is sent after the action has executed and will receive all the data from the action's execution to allow enriching the message.

There is a rich library of notification types in the Stubber Platform which enable sending on different notification platforms.

Record Metrics

An action can record certain metrics after it has performed the tasks. The Stubber Framework allows for defining metrics as plugins, enabling extensibility. Each metric has parameters that allow injecting data from the stub into the metric.

Common metric examples are :

  • Record the number of actions run
  • Record the number of notifications sent by type
  • Record the duration of time between states
  • Record the duration of time until a certain action is run

There is a rich library of metric types in the Stubber Platform which enable great statistical analysis.

Transition State

An action can define an optional transition to a different state. After the action is executed, it can conditionally change the state of the stub. This is called a "to_state" setting. Usually, there is only one "to_state"; however, the framework supports multiple "to_states" with conditional transitions.

Section C.2 Stub Flow Execution

The Stubber Framework uses states and actions to achieve a flexible flow framework.

Stub Creation

When the platform creates a new stub, it will set the state to the start_state defined in the details of the flow. The stub will be allocated a new stubref. The stub will then run the system action *_create_, which sets up the stub for use.

Actions Execution

The platform will display the actions available in the respective state for the specific stub. A user, system, or AI can then choose from the list of available actions which best represents the next step in the process for that template and context. When the action is chosen, the user, system, or AI is presented with a form containing the fields that represent the data collection for that particular action. This is called "want_to," representing the intent of the user to run a particular action. After filling in the form, the user, system, or AI can submit the action, which is called "do_now." The platform will then save the data from the fields and run the tasks specified on the action. If the tasks succeed according to the parameters set on each, the platform will submit the notifications to each notification platform. After the notifications, the platform will record the metrics for the action.

Appendix

Index of Terms

  • Stubber Framework - The conceptual definition of the framework
  • Stubber Platform - The online Saas Platform that implements the framework
  • Template - The high level abstraction of a process definition
  • Stub - The high level abstraction of an instance of a template, the workhorse of the Stubber Framework
  • Branch - A logical grouping of structure representing a draft or live environment
  • Context - A part of the structure that represents different high level functionality of creation, management and default execution of the template.
  • Parts - Flow and Layout
  • Layout - Defines how the Stub is displayed visually in the platform
  • Flow - The main definition part of the template where the states and actions are defined
  • State - A finite state that a Stub can be in, lists the available actions
  • Action - The primary executable part of the Framework, can collect data with fields, run tasks, send notifications, record metrics and transition state
  • Fields - Data collection on an action
  • Tasks - Executable tasks to allow real world activity when an action is run
  • Notifications - Messages send on various notification platforms
  • Metrics - Statistical metrics about the Stub
Previous <- Standard Emitters
Next Reference Section ->