Core Objects

This page provides a complete reference for all core objects in Veratrace, organized by persona use case. Understanding these objects is essential for effectively using and administering Veratrace. Related: Source: Feature Inventory

​

Purpose

This concept page defines all core data objects in Veratrace, their fields, and how different personas (end users, administrators, developers) interact with them.

​

Scope

This page covers:

• All core objects (Instance, TWU Model, Agent, Integration, User, Work Ledger Entry)
• Object fields and data types
• Persona-specific use cases
• UI routes for each object
• API endpoints for each object

This page does not cover:

• Detailed API reference (see API Reference)
• Workflow guides (see Common Workflows)
• Data model relationships (see Data Model Reference)

​

Instance

​

Definition

Multi-tenant configuration container. Each instance has isolated data and authentication. Multi-tenant configuration container. Each instance has isolated data and authentication. Fields:

• id (string) - Instance identifier
• userPoolId (string) - AWS Cognito User Pool ID (format: region_xxxxxxxx)
• clientId (string) - Cognito OIDC client ID
• region (string) - AWS region (extracted from userPoolId)

Admin Use: Configure instance authentication and isolation Developer Use: Instance ID is required for all API calls: /instances/:instanceId/{resource} Source: Source: Feature Inventory

​

Use Cases

Admin Use: Configure instance authentication and isolation Developer Use: Instance ID is required for all API calls: /instances/:instanceId/{resource} Source: Source: Feature Inventory

​

TWU Model

​

Definition

Defines the structure for Trusted Work Units. Models have versions with statuses. Fields:

• id / modelId (string) - Model identifier
• name (string) - Model name
• description (string) - Model description
• status (string) - Model status: DRAFT, PUBLISHED, ARCHIVED
• entities (array) - List of entity definitions
• actions (array) - List of action definitions
• events (array) - List of event definitions
• outcomes (array) - List of outcome definitions with expressions
• version (number) - Version number
• createdAt (timestamp) - Creation timestamp
• updatedAt (timestamp) - Last update timestamp

​

Use Cases

End User Use: View published models to understand work structure Admin Use: Create and manage models, publish versions Developer Use: Create models via API, manage versions programmatically UI Routes:

• /twu-models - List models
• /twu-models/create - Create model
• /twu-models/:modelId/versions/:version/edit - Edit version

Source: Source: Feature Inventory

​

Agent

​

Definition

AI or human agent that performs work operations. Fields:

• id (string) - Agent identifier
• name (string) - Agent name
• type (string) - Agent type: “AI” or “HUMAN”
• active (boolean) - Whether agent is active
• capabilities (array) - Agent capabilities (varies by type)
• model (string, AI only) - AI model identifier (e.g., “gpt-4”, “gpt-3.5-turbo”, “claude-3”)
• priority (string) - Priority level: “high”, “medium”, “low”
• metadata (object) - Additional agent metadata

​

Use Cases

End User Use: View available agents and their capabilities Admin Use: Create and configure agents, set priorities Developer Use: Manage agents via API, configure AI models programmatically UI Routes:

• /agents - List agents
• /agents/create - Create agent
• /agents/:agentId/edit - Edit agent

Source: Source: Feature Inventory

​

Integration

​

Definition

Connection to external systems for evidence ingestion. Fields:

• id (string) - Integration identifier
• name (string) - Integration name
• type (string) - Integration type (40+ types supported)
• status (string) - Status: “active”, “inactive”, “connecting”, “error”
• metadata (object) - Integration-specific configuration
• health (object) - Health check information
  • isHealthy (boolean)
  • lastHealthCheck (timestamp)
  • metrics (object)

​

Use Cases

End User Use: Monitor integration health and status Admin Use: Create and configure integrations, test connections Developer Use: Manage integrations via API, implement custom integrations UI Routes:

• /integrations - List integrations
• /integrations/create - Create integration
• /integrations/:integrationId/edit - Edit integration

Source: Source: Feature Inventory

​

User

​

Definition

User account within an instance. Fields:

• id (string) - User identifier
• username (string) - Username
• email (string) - Email address
• name (string) - First name
• middleName (string, optional) - Middle name
• familyName (string, optional) - Family name
• enabled (boolean) - Whether user is enabled
• temporaryPassword (string, optional) - Temporary password for new users
• roles (array, inferred) - User roles (structure not found in code)

​

Use Cases

Admin Use: Create and manage users, assign roles, enable/disable accounts Developer Use: Manage users via API, integrate with identity providers UI Routes:

• /users - List users
• /users/create - Create user
• /users/:userId/edit - Edit user

Source: Source: Feature Inventory

​

Work Ledger Entry

​

Definition

Record of a TWU execution/work operation. Fields:

• id (string) - Entry identifier
• title (string) - Entry title
• description (string) - Entry description
• type (string) - Entry type (e.g., “TWU”)
• status (string) - Execution status (e.g., “completed”, “in_progress”)
• createdAt (timestamp) - Creation timestamp
• updatedAt (timestamp) - Last update timestamp
• entityId (string) - Related entity identifier
• relatedEntity (string) - Related entity display name
• actors (array) - Actor types: [“AI”], [“HUMAN”], or [“AI”, “HUMAN”]
• activeTime (number) - Active time in seconds
• cost (number) - Cost in dollars
• policyStatus (string) - Policy compliance status: “compliant”, “non_compliant”, “review_required”
• modelName (string) - TWU model name used

​

Use Cases

End User Use: View work executions, monitor compliance, analyze metrics Admin Use: Review policy compliance, audit work operations Developer Use: Query work ledger via API, build analytics dashboards UI Route:

• /ledger - View work ledger entries

Source: Source: Feature Inventory

​

Troubleshooting

​

Object Not Found

Cause: Object ID is invalid or object doesn’t exist Solution:

• Verify object ID is correct
• Check if object exists in the instance
• Ensure you have access to the instance

Source: Source: Feature Inventory

​

Cannot Access Object

Cause: Insufficient permissions or wrong instance Solution:

• Verify you have appropriate role (Administrator, Manager, Editor, or Viewer)
• Check you’re accessing the correct instance
• Ensure object belongs to your instance

Source: Source: Feature Inventory

​

Related

• Terminology - Key terms
• Data Model Reference - Complete data model reference