Papers

Stubber Paper

Paper about the Stubber Framework

Stubber Paper

This paper outlines the key concepts in the Stubber Framework.
The Stubber Framework is a structured way of defining any organizational process.
The word process here is used very liberally as a process in the Stubber Framework can be anything that can be automated or collaborated on.
The Stubber Framework can be used to bring about organizational efficiencies and better collaboration.
The Stubber Framework is the basis for the Stubber Platform which is an online platform that implements these concepts and ideas.
The Stubber Platform is hosted at app.stubber.com.
The Stubber Framework differentiates itself by providing more clarity and more flexibility.

The Stubber Framework

The Stubber Framework is a formal framework based on the idea of a finite state machine (FSM) in which an object can be in only 1 of a set of finite states.
The Stubber Framework goes further than a typical FSM by defining in detail the actions that transition the state.
States and Actions form the 2 most important components of the Stubber Framework.

The framework allows us to map any real-world process into a structure to represent that reality.
The framework gives us a way of thinking about processes and a way of turning the messiness of the real-world into a more manageable form.
The framework also has to enable execution of the process in 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.

Said differently, there can be many stubs all having the same template.
For example if we have a template called "Sales Enquiry" then for each interested customer we will have a "Sales Enquiry" stub.
We can say we have 100 Sales Enquiry stubs.
Similarly if we had a template called "Employee Onboarding" then for each employee we onboard into the organization we would have "Employee Onboarding" stub. 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 are descriptive and contain multiple words so that when an organization defines many templates there is enough clarity to differentiate between the templates.
For example if we have "Sales Enquiry" and we have multiple diverse needs for "Sales Enquiry" then it would be better to call them "General Sales Enquiry" and "Enterprise Sales Enquiry" if they are 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 and 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" or "The Order Number X23" or "The onboarding for employee Jack".
Using a stubref gives you the ability to uniquely identify the single stub that contains all the information for the specific template.
Using stubref solves many instances of confusion in organizations where there exist many differing reference standards and differing references from multiple different systems.
Using stubref simplifies referencing across multiple organizations too.

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 large period of time in the process.
Each individual stub can only be in one state at any given time.
The state should provide anybody 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 have 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

There is a lot to the art of naming the state correctly. It depends on the process.
Sometimes you would want to make the state quite general and leave it more loosely defined for example "customer-onboarding-in-progress" which could allow for a diverse set of possible actions that can be performed.
At other times you would want to narrowly define the state for example "customer-call-pending", "customer-creation-in-progress", "customer-welcome-email-pending" which would represent very strict 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 naming of the action should allow a person, system or artificial intelligence to choose their desired path through the process easily.

An action should begin with a verb ideally. An action should 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 confuse the action with the 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 higher level related to the 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 nSentence Test

If you have named your action well you should be able to test if the following sentences make sense.
You should be able to prefix "I want to [action]". For example "I want to authorize_cost".
You should be able to say "[action] is what Jack did". For example "approved_quote is what Jack did".

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, this enables 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 to enrich the message.
Each notification needs to specify the contacts that the notification is to be sent to.

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 the action has performed the tasks.
The Stubber Framework allows for defining metrics as plugins, this enables 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 1 to_state, however the framework does support 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 busy*start_state that is set 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 that are 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, then 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

Credits

Written by Stuart Procner