Workspaces
Understand and configure workspaces, the foundation of your AI Builder applications
A workspace is the foundation of your AI Builder projects. It provides a complete environment for building, configuring, and deploying your AI applications.
What is a Workspace?
A workspace is a project that:
- Enables various Automations inside your organization, connecting your APIs and systems
- Is easily configurable through workspace config, Apps, and automation graphs
- Produces events recording activities and optionally triggering automations
- Presents computed data through Web Pages accessible to admins or external users
- Has configurable roles providing distinct user groups with fine-grained permissions
Workspaces serve as isolated environments where you can create, test, and deploy complete AI-powered solutions.
A workspace is a project that:
- Enables various Automations inside your organization, connecting your APIs and systems
- Is easily configurable through workspace config, Apps, and automation graphs
- Produces events recording activities and optionally triggering automations
- Presents computed data through Web Pages accessible to admins or external users
- Has configurable roles providing distinct user groups with fine-grained permissions
Workspaces serve as isolated environments where you can create, test, and deploy complete AI-powered solutions.
A workspace contains several key components:
- Configuration: Settings and parameters that define workspace behavior
- Automations: Backend processes that execute logic and workflows
- Pages: User interfaces built with blocks to interact with users
- Apps: Integrated applications that extend functionality
- Security: Role-based access control settings
- Events: Activity tracking and communication system
- Repositories: Version control connections
These components work together to create a complete application environment.
Workspace Configuration
The workspace config provides centralized settings and parameters for your entire workspace.
Basic Configuration
Basic Configuration
Workspace configuration is defined in the workspace source code:
The config.value field is exposed as a config variable inside your automations, making these settings accessible throughout your workspace.
You can reference other config values within your configuration using the {{config.PROPERTY}} syntax, as shown in the LOGIN_URL example above.
Using Secrets
Using Secrets
For sensitive configuration values, use secrets:
Secrets provide a secure way to store and use sensitive information like API keys, passwords, and tokens without exposing them in your code.
Secrets with names starting with prismeai_* are reserved for super admins to configure system settings by workspace.
Environment Variables
Environment Variables
You can also inject configuration values from environment variables:
This environment variable would set config.API_URL for a workspace with the slug “test”. Workspace config takes precedence over environment variables.
Configuration Schema
Configuration Schema
For more controlled configuration, especially for Apps, you can define a schema for your config:
This schema defines the structure, types, and defaults for your configuration, providing better validation and documentation.
Workspace Events
Each workspace maintains a continuous real-time stream of events that describe activities and interactions:
Workspaces work with two main types of events:
- Native Events: Automatically generated by the platform (updates, webhooks, errors, automation executions, etc.)
- Custom Events: Emitted by your automations or installed apps
Events are stored for up to 3 years and can be viewed/searched from the Activity view of the workspace.
Events from workspaces inactive for longer than 15 days and with fewer than 100 events are regularly deleted. Events from deleted workspaces are kept for up to 6 months after deletion.
Workspaces work with two main types of events:
- Native Events: Automatically generated by the platform (updates, webhooks, errors, automation executions, etc.)
- Custom Events: Emitted by your automations or installed apps
Events are stored for up to 3 years and can be viewed/searched from the Activity view of the workspace.
Events from workspaces inactive for longer than 15 days and with fewer than 100 events are regularly deleted. Events from deleted workspaces are kept for up to 6 months after deletion.
Every event includes a type, payload and source fields. Those contains important information:
- type: Type of the given event (can also represent the name of the event)
- payload: Payload of the event, contains useful data specific to the event type
- source.userId: Authenticated user ID (only set for user-emitted events)
- source.sessionId: Session ID shared by all events related to a user session
- source.correlationId: Unique ID shared by events related to the same initial trigger
- source.automationSlug: Automation that emitted the event
- source.appInstanceFullSlug: Source app instance slug (if applicable)
- source.http: Source HTTP request details (if applicable)
This information helps track the origin and context of each event.
Events serve several key purposes in workspaces:
- Recording Activity: Maintaining an audit trail of system and user actions
- Triggering Automations: Events can start automation workflows
- Inter-Component Communication: Components can communicate via events
- Monitoring and Analytics: Events provide insights into system usage
For security reasons, events emitted from a nested app (an app installed within another app) will not be visible in the root workspace events feed.
Activity View
Activity View
The Activity view provides a real-time window into your workspace events:
- Filter Events: Narrow down by event type, source, or time range
- Inspect Details: View complete event data including payload and source
- Track Correlations: Follow chains of related events
- Debug Issues: Identify problems by examining event flows
This view is invaluable for monitoring, debugging, and understanding your workspace’s behavior.
Workspace Secrets
Secrets provide a secure way to store sensitive information like API keys, passwords, and access tokens.
Managing Secrets
Managing Secrets
Workspaces can have secrets provided through:
- The web interface
- API calls
- CI pipeline integration with an external secrets manager
By default, only workspace owners can access these secrets.
You can manage secrets programmatically using the /workspaces/:workspaceId/security/secrets API.
Using Secrets
Using Secrets
Secrets can be used in:
- Workspace Configuration:
- Repository Configuration:
Secrets beginning with prismeai_* are reserved for super admins to configure system settings.
Version Control
Workspace versioning allows you to save the current state of your workspace to a remote git repository, providing backup, history, and collaboration capabilities.
Repository Configuration
Repository Configuration
Configure version control in your workspace source code:
Different authentication methods are supported:
- Username/Password: For basic authentication
- Personal Access Tokens: For services like GitHub (use as password)
- SSH Keys: For secure key-based authentication
You can configure multiple repositories with different access modes:
- read-write (default): Both push and pull operations
- read-only: Only pull operations
- write-only: Only push operations
Push and Pull Operations
Push and Pull Operations
Once a repository is configured:
- Push: Save the current workspace state to the repository
- Pull: Update the workspace from the repository
A native repository named “Prismeai” is always available for saving versions to the platform’s storage. However, these versions are lost if the workspace is deleted, unlike with external Git repositories.
Versioning saves the workspace’s static configuration, including security roles, automations, pages, blocks, and apps, but not dynamic data like events, collections, or uploaded files.
Excluding Files from Import
Excluding Files from Import
When pulling from a repository, you can exclude specific parts of your workspace from being overwritten:
This is useful for preserving local customizations while still getting updates from the shared repository.
Import Results
Import Results
After each archive import or repository pull, a workspaces.imported event is emitted with details:
This event provides a complete record of what changed during the import.
Custom Domains
You can attach a custom domain to your workspace to display pages under your own domain name.
Add DNS Record
Add a CNAME entry to your domain pointing to pages.prisme.ai
For root domains, use an ALIAS record instead of a CNAME.
Configure Workspace
Add the domain to your workspace configuration:
Activate Custom Domain
For Enterprise version, contact support to complete the setup.
JSON Schema Form
Workspace configuration often uses JSON Schema Form, a standard for creating declarative complex forms. This is particularly important for app configuration.
Basic Schema Form
Basic Schema Form
A schema form starts with a single field, typically of type “object”:
This creates a form with two fields, producing an object with “firstname” and “lastname” properties.
Field Types
Field Types
Fields can have various types:
- string: Text input
- localized:string: Translatable text
- number: Numeric input
- localized:number: Translatable numbers
- boolean: Switch button
- localized:boolean: Translatable booleans
- object: Nested object with properties
- array: List of items
Additional attributes include:
- title: Field label
- description: Help text
- default: Default value
- enum: List of allowed values
- enumNames: Display labels for enum values
- required: Whether the field is required
- pattern: Validation regex
- hidden: Whether to hide the field
Advanced Schema Features
Advanced Schema Features
Schema forms support advanced features:
Custom Widgets
Conditional Fields (oneOf)
Arrays and Objects
Form Validation
Form Validation
Schema forms include validation rules. Each rule can just have a true value to display default message with default behavior but can also be an object with value and message. A field can have many validators. The list of validators is :
- required: the value is required
- min: the value as number must be greater than validator value
- max: the value as number must be lower than validator value
- email: the value must be a valid email address
- tel: the value must be a valid phone number
- date: the value must be a valid Date
- minLength: the value as string must have a greater length than validator value
- maxLength: the value as string must have a lower length than validator value
- pattern: the value must match the regular expression set in validator value.
The following exemple show some implementations of validators:
Complete Example
Complete Example
Here’s a more complete schema form example:
This form collects personal information with various field types and widgets.