Skip to main content

Protocol Visual Editors

SureStage supports 30+ protocol types beyond REST/HTTP. Each protocol has a dedicated visual editor that lets you configure mock definitions through forms, trees, and grids instead of writing raw JSON. This guide covers all available protocol editors and how to use them.

Overview​

The Protocol Visual Editor opens when you click Edit Definition on any non-HTTP protocol simulation. Instead of manually crafting JSON, you use a tailored interface designed for that protocol's specific needs.

Why Use Visual Editors?​

  • No JSON required - Build configurations through familiar UI patterns
  • Protocol-specific - Editors are designed for each protocol's data model
  • Validation - Real-time feedback on configuration errors
  • Faster setup - Pre-built templates for common patterns
  • Less error-prone - Guided structure prevents invalid configurations

Editor Access​

  1. Navigate to your protocol simulation
  2. Click Edit Definition to open the modal
  3. Use the visual editor to configure the mock definition
  4. Click Save Definition to persist changes
  5. Optionally enable Reload running server to hot-reload without restarting

Protocol Groups​

Protocols are organized by category and editor type. Each group uses a UI pattern optimized for that protocol's data structure.

Group A — File & Directory Protocols​

Protocols that simulate file systems and directory structures.

ProtocolEditor TypeKey Features
SMBFile tree editorDrag-drop folder structure, file content, permissions, share settings
SFTPFile tree editorSSH-based file system, directory listing, file access
S3File tree editorBucket structure, object metadata, versioning, lifecycle policies
LDAPDN tree editorDistinguished names, attributes, search filters, user objects
JDBCTable editorDatabase tables, columns, rows, SQL query results

Using File Tree Editors (SMB, SFTP, S3)​

  1. Click New Folder to create directory structure
  2. Click New File to add files
  3. Configure file properties:
    • Name - File or folder name
    • Content - File data (text or binary)
    • Metadata - Size, timestamp, permissions
  4. Drag and drop to organize hierarchy
  5. Right-click for context menu (rename, delete, duplicate)
tip

For S3, you can configure object versioning and lifecycle rules per bucket. For SMB/SFTP, set file permissions and share-level access controls.

Using LDAP Directory Editor​

  1. Build DN hierarchy starting with root
  2. Add user and group objects
  3. Configure attributes:
    • CN (Common Name) - Object identifier
    • OU (Organizational Unit) - Container structure
    • Custom Attributes - Any custom LDAP attributes
  4. Set search filters and base DN for queries
  5. Test DN path resolution

Using Table Editor (JDBC)​

  1. Click New Table to create database tables
  2. Define schema:
    • Table Name - Database table identifier
    • Columns - Column name, type, constraints
    • Primary Key - Unique identifier(s)
    • Indexes - Query optimization
  3. Add rows directly in grid view
  4. Configure SQL query results for SELECT statements
info

JDBC editor supports common data types: INT, VARCHAR, TIMESTAMP, DECIMAL, BOOLEAN, and JSON.

Group B — Document Stores​

Protocols that store semi-structured documents and collections.

ProtocolEditor TypeKey Features
MongoDBList + JSON hybridCollections, documents, indexes, aggregation pipelines
DynamoDBList + JSON hybridTables, items, key schema, global secondary indexes
ElasticsearchList + JSON hybridIndices, mappings, documents, analyzer settings
VectorDBList + JSON hybridCollections, vectors, similarity search, embeddings

Using Document Store Editors​

  1. Click New Collection (MongoDB/Elasticsearch) or New Table (DynamoDB)
  2. Configure collection metadata:
    • Name - Collection identifier
    • Schema - Field definitions (optional for MongoDB)
    • Settings - Sharding, replication, TTL
  3. Add documents in two ways:
    • Form mode - Fill out fields in a structured form
    • JSON mode - Paste or edit raw JSON
  4. For search capabilities:
    • Configure indexes on frequently queried fields
    • Set up analyzer settings (Elasticsearch)
    • Define embedding dimensions (VectorDB)
caution

For VectorDB, ensure your vector dimensions match the embedding model. A 1536-dimension embedding requires correctly configured vector fields.

Group C — Message Brokers​

Protocols for event streaming and asynchronous messaging.

ProtocolEditor TypeKey Features
KafkaTopic/queue list + message editorTopics, partitions, seed messages, consumer groups
MQTTTopic/queue list + message editorTopics, QoS levels, retained messages, subscriptions
AMQPTopic/queue list + message editorExchanges, queues, bindings, routing keys
SQS/SNSTopic/queue list + message editorQueues, topics, subscriptions, message attributes

Using Message Broker Editors​

  1. Click New Topic or New Queue to create channels
  2. Configure channel properties:
    • Name - Topic/queue identifier
    • Partitions/Shards - Data distribution (Kafka, AMQP)
    • QoS Level - Message delivery guarantee (MQTT)
    • Retention - How long messages persist
  3. Add seed messages:
    • Click Add Message in the topic/queue
    • Enter message key and payload
    • Set headers or attributes
    • Configure expiration if needed
  4. For advanced configuration:
    • Set consumer groups (Kafka)
    • Configure dead-letter queues (SQS)
    • Set up exchange bindings (AMQP)
info

Kafka partitions allow parallel processing. MQTT QoS levels control delivery guarantees: 0 (at most once), 1 (at least once), 2 (exactly once).

Group D — Identity & Auth​

Protocols for user identity and access management.

ProtocolEditor TypeKey Features
OAuth2Entity card editorClients, access tokens, scopes, grant types
SAMLEntity card editorIdentity provider config, service provider metadata, assertions
SCIMEntity card editorUsers, groups, schemas, resource types

Using Identity Editors​

  1. Click New Entity to create users, clients, or providers
  2. Configure entity properties:
    • ID - Unique identifier
    • Name - Display name
    • Attributes - Type-specific fields
  3. For OAuth2:
    • Define clients with client IDs
    • Assign scopes (e.g., read:users, write:posts)
    • Set grant types (authorization_code, client_credentials)
    • Configure token expiration
  4. For SAML:
    • Upload IdP certificate
    • Configure assertion attributes
    • Set NameID format
    • Define attribute mappings
  5. For SCIM:
    • Create users with attributes
    • Create groups with members
    • Define custom schemas
    • Set resource type permissions
tip

For OAuth2, use standard scopes like openid profile email for better interoperability. For SAML, test assertion validation carefully as encoding issues are common.

Group E — Schema-Driven APIs​

Protocols that use formal schema definitions like GraphQL and gRPC.

ProtocolEditor TypeKey Features
GraphQLCode editor + method gridSDL schema, resolvers, queries/mutations, subscriptions
gRPCCode editor + method gridProto definitions, services, methods, message types
SOAPCode editor + method gridWSDL, operations, message types, bindings
ThriftCode editor + method gridIDL, services, structs, enums

Using Schema Editors​

  1. Configure the schema in the Schema Panel:
    • For GraphQL: Paste GraphQL SDL
    • For gRPC: Paste Proto3 definition
    • For SOAP: Paste WSDL or define operations
    • For Thrift: Paste Thrift IDL
  2. Click Validate Schema to check syntax
  3. Once validated, the Method Grid appears showing:
    • All available operations/methods
    • Input and output types
    • Description and documentation
  4. Configure resolvers:
    • Click Configure Response for each method
    • Define mock response data
    • Set error scenarios
    • Add response delays
caution

GraphQL schemas are case-sensitive. Ensure type names match exactly when referencing them in resolvers. For gRPC, proto3 syntax is recommended for better compatibility.

Group F — Streaming Protocols​

Real-time protocols for push communication and event streaming.

ProtocolEditor TypeKey Features
WebSocketChannel list + event builderChannels, message handlers, bidirectional events
SSEChannel list + event builderEvent streams, event types, data patterns

Using Streaming Editors​

  1. Click New Channel to create communication channels
  2. Configure channel properties:
    • Name - Channel identifier
    • Description - What this channel represents
    • Auth Required - Authentication for this channel
  3. Add events to the channel:
    • Click New Event in the channel
    • Define event name and schema
    • Configure event payload
  4. For WebSocket:
    • Set up bidirectional handlers
    • Configure message acknowledgment
    • Set up connection lifecycle events (connect, disconnect)
  5. For SSE:
    • Define server-sent events
    • Set event emission frequency
    • Configure retry behavior
    • Set data format (JSON, text, binary)
info

WebSocket connections are persistent. SSE is unidirectional (server to client only), making it simpler for many use cases but less suitable for true bidirectional communication.

Group G — Infrastructure Protocols​

System-level protocols for monitoring, configuration, and operations.

ProtocolEditor TypeKey Features
SMTPSmart defaultsMail server config, mailbox simulation, message templates
RedisSmart defaultsKey types, commands, data structures, expiration
SyslogSmart defaultsFacility, severity, message format, log aggregation
StatsD/PrometheusSmart defaultsMetrics, counters, gauges, histograms, labels
OTLPSmart defaultsTraces, spans, metrics, logs, resource attributes
OPASmart defaultsPolicies, data, decision rules, test bundles

Using Smart Default Editors​

Smart default editors provide pre-configured templates for common infrastructure scenarios. They require minimal configuration:

  1. Review the default configuration presented
  2. Customize as needed:
    • Add specific metrics (Prometheus)
    • Configure mail rules (SMTP)
    • Set policy rules (OPA)
  3. Examples provided for common patterns:
    • Response time histogram (Prometheus)
    • Email validation policy (OPA)
    • Log severity levels (Syslog)
  4. Click Save to apply defaults

Protocol-Specific Options:

  • SMTP - Simulate mailbox behavior, bounce handling, delivery delays
  • Redis - Set key expiration, configure persistence, simulate eviction
  • Syslog - Filter by facility/severity, configure forwarding
  • StatsD/Prometheus - Define metric types and labels, set scrape intervals
  • OTLP - Configure sampling rates, resource detection, exporter settings
  • OPA - Load policy bundles, configure data, test policy decisions
info

Most infrastructure protocols work best with realistic default configurations. The smart defaults provide templates that match real-world deployments, reducing setup time.

Group H — Agent & Webhook Protocols​

Protocols for agent-to-agent communication and external integrations.

ProtocolEditor TypeKey Features
A2AEntity card editorAgent cards, skills, task handling, routing
ACPEntity card editorAgent capabilities, permissions, delegation rules
WebhooksEntity card editorEndpoints, payloads, delivery config, retry policies

Using Agent & Webhook Editors​

  1. Click New Entity to create agents, capabilities, or webhooks
  2. Configure entity properties:
    • ID - Unique identifier
    • Name - Display name
    • Config - Type-specific settings
  3. For A2A (Agent-to-Agent):
    • Define agent capabilities (skills)
    • Configure routing rules
    • Set up task handling behavior
    • Define inter-agent protocols
  4. For ACP (Agent Capabilities):
    • Define capabilities available to agents
    • Set permission levels
    • Configure delegation rules
    • Define resource access
  5. For Webhooks:
    • Set webhook URL pattern
    • Configure request headers
    • Define payload schema
    • Set delivery and retry options
tip

For webhook testing, configure retry policies with exponential backoff. For A2A, document the capability contract clearly so consuming agents understand the interface.

Mock Definition Editor​

The Mock Definition Editor is the central interface for all protocol editors. It provides consistent features across all 30+ protocols.

Editor Modes​

The editor supports two modes that work together:

Visual Mode

  • Use protocol-specific editor (file tree, form, grid, etc.)
  • Configuration updates automatically reflected in JSON
  • Recommended for most use cases

JSON Mode

  • Edit raw JSON directly
  • Full control over all properties
  • Use when visual editor doesn't support a feature
  • Real-time validation and error highlighting

Switching Between Modes​

  1. Look for Visual and JSON tabs at the top of the editor
  2. Click to switch modes
  3. Changes sync bidirectionally - edit in visual, see updates in JSON
  4. If JSON is invalid, visual mode is disabled until fixed

Save and Reload Options​

After editing:

  1. Click Save Definition to persist changes
  2. Optionally enable Reload running server:
    • Without reload: Changes apply to new requests only
    • With reload: Existing connections are gracefully closed and reconnected with new config
  3. Click Cancel to discard changes
caution

Reloading a running server briefly interrupts active connections. Schedule reloads during low-traffic periods for production mocks.

AI Mock Definition Generator​

Quickly generate mock definitions using AI instead of building them manually.

Enabling AI Generation​

  1. Look for AI Mock Definition Generator panel at the top of the editor
  2. Toggle Enable AI to expand the panel
  3. Requires the ai_response_generation feature flag to be enabled

Quick Templates​

Choose a pre-built template matching your use case:

  • E-commerce - Product catalog, shopping carts, orders, payments
  • Healthcare - Patient records, prescriptions, appointments, billing
  • Fintech - Accounts, transactions, transfers, fraud detection
  • IoT - Sensor data, device management, telemetry, alerts
  • Social Media - Users, posts, followers, messaging, notifications

Custom Prompt​

Or write your own prompt describing the data structure:

"Generate a Kafka topic with 10 seed messages representing real-time stock price updates. Each message should include symbol, price, volume, and timestamp."

Generation Process​

  1. Select template or write custom prompt
  2. Click Generate Preview to create a definition
  3. Review the JSON preview that appears:
    • Check structure and data types
    • Verify it matches your requirements
    • Scroll through entire definition
  4. Click Use This Definition to apply to the visual editor
  5. Make any manual adjustments
  6. Click Save Definition
info

AI-generated definitions provide a good starting point but may need refinement. Always review generated content before deploying to production mocks.

JSON Fallback Editor​

All protocols support direct JSON editing for maximum flexibility.

Accessing JSON Editor​

  1. Click the JSON tab in the editor modal
  2. Full JSON editor appears with syntax highlighting
  3. Edit the definition directly

Features​

  • Syntax highlighting - Color-coded JSON structure
  • Real-time validation - Error messages appear as you type
  • Auto-formatting - Press Cmd+Shift+F (Mac) or Ctrl+Shift+F (Windows) to format
  • Copy/paste - Copy JSON from other tools and paste here
  • Keyboard shortcuts:
    • Cmd+S (Mac) or Ctrl+S (Windows) - Save
    • Esc - Cancel and close
    • Cmd+Z (Mac) or Ctrl+Z (Windows) - Undo

JSON Schema Reference​

Each protocol has a specific JSON schema. When editing JSON:

  1. Hover over fields for inline documentation
  2. Invalid fields show error tooltips
  3. Required fields are marked with asterisks
  4. Consult protocol documentation for full schema
caution

JSON mode requires correct syntax. A single missing comma or bracket will prevent saving. Use the error messages to identify issues quickly.

Protocol Editor Examples​

Example 1: MongoDB Collection with Documents​

Scenario: Set up a mock MongoDB database for an e-commerce API.

  1. Click New Collection and name it "products"
  2. Configure collection schema:
    • _id (ObjectId) - Auto-generated
    • name (String)
    • price (Number)
    • inventory (Number)
    • tags (Array of Strings)
  3. Click New Document and add sample products:
    • Product 1: "Laptop", 999.99, 5 in stock, tags: ["electronics", "computers"]
    • Product 2: "Mouse", 29.99, 50 in stock, tags: ["electronics", "accessories"]
  4. Create an index on the "name" field for search optimization
  5. Save the definition

Example 2: GraphQL API with Queries and Mutations​

Scenario: Mock a social media GraphQL API.

  1. Paste GraphQL SDL schema: 
    type Query {
      user(id: ID!): User
      posts(limit: Int): [Post!]!
    }

    type Mutation {
      createPost(input: CreatePostInput!): Post!
    }

    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Post {
      id: ID!
      title: String!
      author: User!
      createdAt: String!
    }

    input CreatePostInput {
      title: String!
      authorId: ID!
    }
  2. Click Validate Schema
  3. Configure resolver responses in the Method Grid:
    • user(id) returns sample user data
    • posts(limit) returns array of posts
    • createPost returns newly created post
  4. Set response delays (e.g., 100ms) for realism
  5. Save the definition

Example 3: Kafka Topic with Seed Messages​

Scenario: Simulate real-time order events.

  1. Click New Topic and name it "orders.events"
  2. Configure topic:
    • Partitions: 3 (for parallelism)
    • Retention: 7 days
  3. Add seed messages (one per partition):
    • Message 1: {"orderId": "ORD-001", "status": "created", "timestamp": "2026-02-21T10:30:00Z"}
    • Message 2: {"orderId": "ORD-002", "status": "confirmed", "timestamp": "2026-02-21T10:31:00Z"}
    • Message 3: {"orderId": "ORD-003", "status": "shipped", "timestamp": "2026-02-21T10:32:00Z"}
  4. Save the definition
  5. Consumers can now subscribe and receive these seed messages

Best Practices​

Design Principles​

  • Start with the template - Use quick templates or AI generation for initial structure
  • Review and customize - Don't deploy AI-generated definitions without review
  • Keep it realistic - Mock data should match production patterns
  • Document intentions - Use descriptions to explain configuration choices

Editor Usage​

  • Visual when possible - Use the protocol-specific editor for most work
  • JSON for fine-tuning - Switch to JSON for precise control
  • Validate often - Check for errors before saving
  • Test after changes - Verify mock behavior after updating definitions

Data Configuration​

  • Use realistic values - Test with data that matches production use cases
  • Include edge cases - Add boundary value examples (min, max, null)
  • Test error paths - Define error responses alongside happy paths
  • Consider scale - Create enough sample data to exercise pagination, filtering, sorting

Troubleshooting​

Definition Won't Save​

  • Check JSON syntax in JSON tab for errors
  • Ensure all required fields are present
  • Look for error messages below the editor
  • Copy JSON to an online JSON validator for debugging

Visual Editor Shows Errors​

  • Switch to JSON mode to see exact error location
  • Validate the JSON syntax
  • Review the protocol's schema documentation
  • Reset to a known-good state and make incremental changes

AI Generation Seems Off​

  • Review the generated definition carefully
  • Verify the template or prompt matched your intent
  • Edit the definition manually to correct issues
  • AI provides starting points, not production-ready definitions

Changes Not Applying​

  • Click Save Definition after making changes
  • Enable Reload running server if changes need immediate effect
  • Check that the simulation is running
  • Verify the protocol type matches expected protocol

Next Steps​