NOTICE: All information contained herein is, and remains
the property of TechnoCore Automate.
The ObjConversationEdit.py module provides YAML-based
import and export of conversation definitions. It follows
the same pattern as ObjWorkflowEdit.py, allowing
conversation flows to be saved to YAML files and loaded
back into the database.
The module contains one class:
| Method | Purpose |
|---|---|
get_conversation_json(conversation_code) |
Fetch conversation, details, and pages as a structured dict |
save_conversation_to_file(conversation, filename) |
Clean and dump conversation dict to YAML |
load_conversation_from_yaml(filename, new_code) |
Read YAML, delete existing records, insert new records |
remove_none_values(data) |
Recursively strip None values from dicts and lists |
remove_empty_strings(data) |
Recursively strip empty string values from dicts |
remove_conversation_code(data) |
Strip ConversationCode key from each dict in a list |
remove_package(data) |
Recursively remove the Package key from dicts |
get_next_version(conversation_code) |
Query current version, return incremented string |
set_version(conversation_code, version) |
Update Version in all three conversation tables |
safe_sql_insert(sql, data) |
Execute parameterised SQL safely |
generate_markdown(conversation) |
Build Markdown document from conversation dict |
generate_mermaid(pages) |
Build Mermaid flowchart from pages list |
save_markdown_to_db(code, md, mermaid) |
Store Markdown and Mermaid in def_conversation |
validate_conversation(conversation) |
Check structural integrity, return list of issues |
The exported YAML file has this structure. Note that
ConversationCode only appears at the top level and
is not repeated inside Details or Pages entries. Empty
strings are stripped from the output to reduce file
size. On load, missing values default to empty strings.
ConversationCode: MY_CONVERSATION
Version: '1'
Conversation:
ConversationCode: MY_CONVERSATION
Title: My Conversation
Description: A sample conversation
Active: Y
Details:
- Channel: CONSOLE
Botname: MyBot
OnWelcomeMessage: Welcome!
PageLength: 5
Pages:
- PageNo: 1
HeaderText: What would you like to do?
Option1: View
Option1Callback: 2
The module operates on three tables defined in
ObjConversation.yaml:
| Table | Role |
|---|---|
def_conversation |
Master conversation definition |
def_conversation_detail |
Per-channel configuration |
def_conversation_page |
Page definitions with options |
Each conversation definition carries a Version
column (varchar(50)) in all three database tables.
On save, the version auto-increments from the
current database value. Supply --version on the CLI
to set an explicit version string instead. A versioned
copy of the YAML file is also written as
{code}_v{version}_conversation.yaml.
On load, the version stored in the YAML top-level
Version key is injected into all three tables.
On save, a Markdown document is generated from the
conversation structure and stored in the
def_conversation.Markdown TEXT column. The document
includes:
On save, a Mermaid flowchart is generated and
stored in the def_conversation.Mermaid TEXT column.
The diagram shows:
page_N["Page N: Name"]OptionOverridePossibleCallbacksBoth Markdown and Mermaid are DB-only reporting fields
and are not saved into the YAML file.
The validate command checks a conversation for
structural issues:
| Check | Description |
|---|---|
| ConversationCode | Must be present |
| Conversation section | Must exist |
| Channels | At least one channel required |
| Pages | At least one page required |
| Entry point | Page 1 must exist |
| HeaderText | Every page must have HeaderText |
| Option callbacks | Targets must reference existing pages |
| Dynamic callbacks | OptionOverridePossibleCallbacks targets checked |
| Dead ends | Pages with no options and no override SQL |
| Orphan pages | Pages not reachable from any callback |
When loading from YAML:
create_tables_from_yaml() is called first toConversationCode field is re-injected from thePackage field is set to the current activedef_conversation anddef_conversation_page. Package is never saved toVersion from the YAML is set on all insertedFiles are stored in local.documents/conversations/.
The directory is created automatically if it does not
exist. When no filename is given, the convention is
{code}_conversation.yaml. On save, a versioned copy
is also written as {code}_v{version}_conversation.yaml.
# Save a conversation to YAML (auto filename,
# auto-increment version, generates Markdown/Mermaid)
python factory.core/ObjConversationEdit.py save CODE
# Save with explicit version
python factory.core/ObjConversationEdit.py save CODE \
--version 2.0
# Save with an explicit filename
python factory.core/ObjConversationEdit.py save CODE \
--filename custom.yaml
# Load a conversation from YAML (auto filename)
python factory.core/ObjConversationEdit.py load CODE
# Load from explicit filename with code override
python factory.core/ObjConversationEdit.py load CODE \
--filename custom.yaml --new-code NEW_CODE
# Activate a previously saved version
python factory.core/ObjConversationEdit.py \
activate CODE 2
# Validate from database
python factory.core/ObjConversationEdit.py \
validate CODE
# Validate from YAML file
python factory.core/ObjConversationEdit.py \
validate CODE --filename custom.yaml
| Module | Relationship |
|---|---|
factory.core/ObjConversation.py |
Base class providing DB access and conversation logic |
factory.core/ObjConversation.yaml |
Schema and queries for conversation tables |
factory.workflow/ObjWorkflowEdit.py |
Reference pattern for YAML import/export |
cythonize -3 -a -i ObjConversationEdit.py
Compiling factory.core/ObjConversationEdit.py
Updated : 2026-01-28