CRM workspace domain
The CRM workspace domain gives a team one shared place to manage people, companies, opportunities, tasks, notes, history, communication, automation, and reports. The workspace is the data and access boundary. Members use linked records through record pages and views, then use timelines, dashboards, connected accounts, and workflows to move work forward. See CRM records and views for record and display flows and Identity, onboarding, and workspace membership for user and access flows.
Workspace boundary
The workspace groups CRM data, product settings, metadata, and member access. A member works inside that boundary through a role. The role sets the base read and change rights. Optional record sharing can widen access to one record without replacing the role model.
Workspace setup creates the standard CRM model and its first work surfaces. Later synchronization brings standard changes into the workspace while it keeps workspace-owned choices. This keeps records, views, search, layouts, dashboards, integrations, and permissions on the same model.
The workspace also holds supporting state for billing, connected accounts, calendar and email channels, feature flags, AI model policy, installed providers, and messaging. Messages keep their thread, participant, campaign, and attachment context inside this boundary. These services extend CRM work, but the workspace remains the point that joins their data and access rules.
References: packages/…/twenty-standard-application.service.ts• L42-156 packages/…/seed-feature-flags.util.ts• L1-37 packages/…/workspaceAiModelsSelector.ts• L8-16 packages/…/message.workspace-entity.ts• L11-27
CRM record model
The CRM model uses records as the shared language for customer context. Each record has one main purpose, while relations connect it to the people, organizations, work, and history around it.
| Record | Purpose | Main context |
|---|---|---|
| Person | Represents an individual contact. | Company, opportunities, tasks, notes, and history |
| Company | Represents an account or organization. | People, opportunities, tasks, notes, and history |
| Opportunity | Represents a sales opportunity. | Company, contact, owner, tasks, notes, and history |
| Task | Represents work that a member must track. | Assignee, target records, state, and due date |
| Note | Stores written context for later use. | Target records and history |
| Timeline activity | Records a dated event or meaningful change. | Target record, related record, and author |
| Dashboard | Presents workspace data for review. | Tabs, widgets, filters, and layouts |
Tasks and notes stay separate from the records they explain. One task or note can support more than one target. This lets the team keep one work item while showing it in each relevant person, company, or opportunity context.
References: packages/…/person.workspace-entity.ts• L24-50 packages/…/company.workspace-entity.ts• L19-47 packages/…/opportunity.workspace-entity.ts• L15-37 packages/…/task.workspace-entity.ts• L10-23 packages/…/note.workspace-entity.ts• L9-18
Record relationships
Relations give each record its business context. A person can belong to a company. An opportunity can connect to a company, a contact, and an owner. A task or note can point to several supported record types.
The product can show a relation from either side. A company can show its people and opportunities. A person or opportunity can show its tasks, notes, and history. The relation picker and record page use the target type and member access to decide which links are available.
Workspace metadata can also define a related record path. This is a named path across active relations. It lets a view or record surface use a deeper connection without adding a new direct relation. The path must follow real relations and must not loop or duplicate an existing path.
The child page CRM records and views explains how these links appear in lists, record pages, and activity views. The child page Identity, onboarding, and workspace membership explains how member roles and access affect them.
References: packages/…/task-target.workspace-entity.ts• L9-19 packages/…/note-target.workspace-entity.ts• L9-19 packages/…/flat-related-record-path-validator.service.ts• L50-200
Work management
Tasks and notes turn record context into team action and shared memory. A task has work state, an assignee, and an optional due date. A note has a title and written content. Both can stay attached to several target records.
Members can create related work from a record page or create records from a view. A new record can inherit the context of a grouped view, then appear in that view when it matches the view rules. This keeps daily work in the same record model as customer data.
Connected accounts can also add contact context. Contact sync creates or restores people and work-domain companies when needed. It matches known email handles to existing people and avoids creating records for the workspace's own members.
References: packages/…/task.workspace-entity.ts• L10-23 packages/…/note.workspace-entity.ts• L9-18 packages/…/create-company-and-contact.service.ts• L52-165 packages/…/match-participant.service.ts• L109-269
Calendar context
Calendar sync brings external events into the workspace so customer activity can share the same record context. Google Calendar, Microsoft Calendar, and CalDAV accounts expose one common change result with changed events, removed events, and a cursor for the next sync.
The sync removes canceled events, queues changed events for import, and records channel progress. Google recurring events use a rolling 90-day horizon when enabled. The workspace schedules a later wake-up to add future instances as they enter that horizon. Paused or failed channels are checked again later instead of losing the recurring event.
References: packages/…/calendar-get-events.service.ts• L14-69 packages/…/calendar-fetch-events.service.ts• L43-162 packages/…/calendar-recurring-event-wake-up.service.ts• L78-167 packages/…/google-calendar-get-events.service.ts• L24-109
Outbound communication
Workspace communication uses connected accounts and CRM people as one context. Members can send a direct email from a record and link the resulting message thread to that record. Campaigns can send to a workspace audience now or later, with person fields available as checked template variables.
Campaign sending moves through audience checks, permission and billing checks, a scheduled or sending state, and queued delivery work. A campaign returns to draft when its scheduled send is no longer valid. A completed campaign records a terminal result after all deliveries settle.
Connected account tokens support these flows without exposing provider credentials across workspaces. The refresh service reuses valid tokens and coordinates concurrent refreshes before it saves new encrypted credentials.
References: packages/…/send-email.resolver.ts• L65-175 packages/…/campaign-variable.service.ts• L57-170 packages/…/message-campaign.service.ts• L163-221 packages/…/message-campaign-schedule.service.ts• L41-167 packages/…/message-campaign-lifecycle.service.ts• L42-78 packages/…/connected-account-refresh-tokens.service.ts• L60-159
Timeline history
The timeline is the shared history for records. It turns meaningful record changes and relation changes into dated activities that a record page can show.
Activity routing decides which changes become history. The system can combine rapid changes that describe one logical event. It keeps linked activity dates aligned with the source record. This gives members one history view without treating every low-level update as a separate business event.
Timeline activity can target standard or custom records. The related record is resolved inside the current workspace and access context. History therefore follows the same visibility boundary as the record that it describes.
References: packages/…/timeline-activity.workspace-entity.ts• L19-53 packages/…/timeline-activity-routing-plan.service.ts• L49-94 packages/…/timeline-activity.service.ts• L113-205 packages/…/useTimelineActivities.ts• L1-96
Record views
Views turn the shared record model into daily work surfaces. A saved view defines which records members see and how the product filters, sorts, groups, or arranges them. The same records can appear in a table, list, board, calendar, or focused record page.
Views support these work patterns:
- Filter by record fields, related records, or member values.
- Group records into board columns or table sections.
- Move calendar records while keeping their date and order.
- Edit one record or update selected records together.
- Import many records with field mapping and upsert behavior.
- Export workspace data when the requester has permission.
Views read current workspace records through the same metadata and access boundary as record pages and dashboards. The child page CRM records and views covers these display and editing flows in detail.
References: packages/…/View.ts• L15-44 packages/…/AdvancedFilterFieldSelectMenu.tsx• L37-91 packages/…/RecordCalendarTopBar.tsx• L63-169 packages/…/record-export.workspace-service.ts• L186-240
Dashboard reports
Dashboards summarize current workspace records for review. A dashboard is a page layout with tabs and widgets. Widgets can show totals, grouped values, time trends, live record tables, rich text, or embedded content.
Chart and record-table widgets use workspace object and field metadata. A widget can name the object and fields directly, while the workspace resolves those names to its current metadata. This keeps dashboard reports usable across standard and custom CRM objects.
The dashboard flow is shared with page layouts. Workspace tools can create a complete dashboard, list dashboards, read a dashboard with its tabs and widgets, and update a widget on either a dashboard or a record page. A record-table widget uses its own dedicated view so its display rules stay separate from an index-page view.
This diagram shows how a dashboard turns workspace data into a report surface.
flowchart LR
A[Workspace records] --> B[Object and field metadata]
B --> C[Widget filters and grouping]
C --> D[Dashboard tabs and layout]
D --> E[Report surface]
The starter dashboard focuses on opportunity health. Teams can change or duplicate its layout without changing the source records. Dashboard and layout creation must remain linked so a failed record create does not leave an unused layout.
References: packages/…/widget.schema.ts• L303-341 packages/…/widget.schema.ts• L583-659 packages/…/update-page-layout-widget.tool.ts• L47-55 packages/…/create-complete-dashboard.tool.ts• L79-135 packages/…/list-dashboards.tool.ts• L30-60 packages/…/get-dashboard.tool.ts• L37-39 packages/…/dashboard-tool.workspace-service.ts• L32-75
Workspace automation
Workspace automation runs workflows that react to records, schedules, webhooks, or member actions. A workflow run records its state in the workspace, then moves through queued work and step results. Runs are scoped to the application that owns the workflow when that application is known. Workspace scope remains the safe boundary when it is not.
Workflow versions must have a valid trigger and at least one valid step before they can become active. Active triggers create runs that pass through throttling and queue work. The run then records step results and can wait, retry, continue, stop, complete, or fail.
Workflow and agent surfaces give members a view of automation health. They show recent runs, run counts, status, duration, and time-based trends. Workflow views also expose failed runs, while agent views can open a readable conversation when one exists. Run data remains subject to the feature and permission rules for that workspace.
Workflow actions can call an MCP tool, which is a tool exposed by a connected external server. The run checks that the server belongs to an application the workflow can reach. Email actions use the run's workspace and actor context, resolve the sender account, and write a step result for the run.
The standard surface exposes record creation, bulk changes, search, import, export, dashboards, workflows, and optional AI actions through context-aware commands. Feature flags and member permissions decide which actions appear.
This diagram shows how an event becomes a workspace-scoped workflow result.
flowchart LR
A[Record, schedule, webhook, or member action] --> B[Validated active workflow version]
B --> C[Workspace and application scope]
C --> D[Queued workflow run]
D --> E[Steps, waits, and retries]
E --> F[Completed or failed run]
References: packages/…/assert-version-can-be-activated.util.ts• L26-90 packages/…/workflow-trigger.job.ts• L35-114 packages/…/core-workflow-runner.service.ts• L50-131 packages/…/run-workflow.job.ts• L40-95 packages/…/workflow-run.workspace-service.ts• L44-233 packages/…/workflow-run-job-scope.workspace-service.ts• L18-71 packages/…/tool-backed.workflow-action.ts• L78-145 packages/…/email-workflow-action.base.ts• L90-152 packages/…/useCoreAgents.ts• L34-96 packages/…/CoreWorkflowOverviewTab.tsx• L18-95
Metadata lifecycle
Workspace metadata describes the objects, fields, relations, views, layouts, widgets, search behavior, roles, and automation that form the CRM surface. A metadata migration compares desired state with current state, validates links and access, then applies the changes in a safe order.
The migration runner updates its working metadata as each action succeeds. It commits the main change, refreshes the related workspace caches, and dispatches deferred operations after commit. A failed transaction rolls back its database work and refreshes the affected cache state. This lets later views, widgets, permissions, and workflows use the same current workspace model.
Object metadata also gives each object a stable visual identity. System objects use a neutral color, standard CRM objects use known colors when no custom color is set, and custom objects use a repeatable color from their singular name. This keeps records and workspace views recognizable when metadata has no explicit color.
References: packages/…/twenty-standard-application.service.ts• L82-155 packages/…/workspace-migration-runner.service.ts• L230-308 packages/…/workspace-migration-runner.service.ts• L388-435 packages/…/workspace-migration-runner.service.ts• L446-607 packages/…/getObjectColorWithFallback.ts• L8-68
Workspace access
Workspace access combines membership, roles, object permissions, field permissions, and optional record sharing. An administrator can manage the full workspace. A member can work only within the rights assigned to the member's role.
Record sharing can make one record private or share it with named people and roles. A record grant gives access to that record. It does not by itself give the right to manage sharing. The member still needs the role permission for that action.
Removing a member also updates workspace-owned access and work context. Connected accounts and record shares can move to a successor. The member link is removed and related chat work is cleaned up. This prevents a removed member from retaining ownership or access through connected systems.
The child page Identity, onboarding, and workspace membership explains authentication, membership, roles, and access state in detail.
References: packages/…/record-sharing.service.ts• L86-177 packages/…/record-access-policy.service.ts• L54-189 packages/…/workspace-member-delete-one.post-query.hook.ts• L45-141 packages/…/useRecordSharing.ts• L19-133
Change scope
The refresh uses these status-tagged entries verbatim:
- M packages/twenty-front/src/modules/object-metadata/utils/getObjectColorWithFallback.ts
Change checklist
When these files or sections are changed, remember to consider these:
- Keep standard objects, fields, relations, views, layouts, widgets, search, roles, permissions, and activity metadata aligned during workspace synchronization.
- Keep relation targets usable in record pages, filters, charts, and access checks. A readable link needs readable target metadata and a readable target record.
- Keep task and note target changes aligned with timeline activity routing.
- Keep related record paths aligned with active relations. Paths must stay ordered, non-cyclic, and unique.
- Keep dashboard widget references and dedicated record-table views aligned with current workspace metadata.
- Keep dashboard records and page layouts together during create, copy, update, and delete flows.
- Keep calendar cursors, removed-event cleanup, recurring-event horizon, and channel sync status aligned across providers.
- Keep connected-account refresh locking, token encryption, and provider support aligned with all calendar and email consumers.
- Keep campaign audience variables aligned with current person fields and keep campaign state transitions aligned with queued delivery state.
- Keep sent message thread links aligned with the target record and workspace auth context.
- Keep timeline routing rules aligned with direct and junction relation targets.
- Keep workflow version validation aligned with the trigger types and action types that the runner can execute.
- Keep workflow run records, queue scopes, throttling, retries, waits, and terminal states aligned across trigger and execution paths.
- Keep application ownership and workspace fallback scope aligned when workflow runs are queued or resumed.
- Keep email workflow sender resolution, input interpolation, tool execution context, and step logs aligned.
- Keep MCP servers and workflow callers inside the same reachable application boundary.
- Keep member removal ownership transfer, record-share transfer, chat cleanup, and workspace-cache refresh as one lifecycle.
- Keep workspace and member identity on every CRM read, write, export, integration, workflow, and chat operation.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Standard metadata is not synchronized after a model change. | Records, views, and dashboards disagree about fields or links. | Synchronize the standard application and validate the workspace migration. |
| A relation target or related-record path is invalid. | A record page, filter, chart, or migration cannot use the link. | Validate target metadata, access, path order, cycles, and duplicates. |
| A task or note relation changes without timeline routing. | The relation works but its change does not appear in history. | Update the activity routing rule with the relation. |
| A dashboard widget names an unknown object or field. | The dashboard cannot build the widget or uses the wrong source. | Resolve names against current workspace metadata before saving or running it. |
| A record-table widget reuses an index view. | Dashboard display rules can leak into normal record views. | Use a dedicated view for each record-table widget. |
| A calendar cursor or removed-event result is not applied. | The workspace keeps stale or duplicated calendar context. | Persist the provider cursor and clean deleted associations before queuing new imports. |
| A recurring event is imported without a horizon wake-up. | Future instances remain missing from the workspace. | Queue instances within the horizon and schedule the next wake-up before the horizon. |
| A connected account refresh races with another refresh. | A rotated refresh token can be consumed or a channel can fail. | Lock per connected account and reuse the winner's valid credentials. |
| A campaign uses an unknown person variable. | The campaign is accepted with broken personalization or cannot send. | Build variables from current person metadata and reject unknown names. |
| A scheduled campaign loses its sender or permission before send time. | The campaign does not send and can remain incorrectly scheduled. | Re-check the scheduler member, audience, permissions, and send readiness before claiming it. |
| A sent message is not linked to its target record. | The conversation is separated from the CRM context. | Persist the thread and link it with the workspace auth context after send. |
| A timeline target relation has incomplete morph or junction metadata. | The activity cannot resolve the record it should describe. | Build target joins only from valid current workspace metadata. |
| A workflow version has no valid trigger or steps. | An invalid workflow can become active or fail only after dispatch. | Validate the version before activation. |
| A workflow run is queued without its owning application scope. | The run may use the wrong integration boundary or fail to reach its tools. | Resolve application scope from the workflow and use workspace scope only as fallback. |
| A run is marked complete while a waiting or retrying step remains. | Later input is ignored or the run reports a false result. | Claim pending steps and keep the run open while waits or retries remain. |
| A queue dispatch fails after a workflow run is created. | The run remains queued without work to execute. | Record the run as failed when enqueueing cannot complete. |
| A workflow action cannot resolve its connected email account. | The action fails without a valid sender and may leave an incomplete step. | Resolve the member's email-capable account inside the workspace before sending. |
| A record share grant is treated as permission to manage sharing. | A member can change access without the required role right. | Require both record access and the role's sharing permission. |
| A removed member keeps owned accounts, shares, or chat work. | Access or work context remains tied to a member outside the workspace. | Transfer owned resources, remove membership, clean chat work, and refresh caches. |
Key files
| File | Why to read it |
|---|---|
| packages/…/twenty-standard-application.service.ts | Shows how the standard CRM model and initial views are synchronized into a workspace. |
| packages/…/person.workspace-entity.ts | Shows the person record and its CRM links. |
| packages/…/company.workspace-entity.ts | Shows the company-centered CRM model. |
| packages/…/opportunity.workspace-entity.ts | Shows the opportunity, owner, company, and contact context. |
| packages/…/task.workspace-entity.ts | Shows the actionable work record. |
| packages/…/note.workspace-entity.ts | Shows the written context record. |
| packages/…/calendar-fetch-events.service.ts | Shows how connected calendar changes enter workspace import. |
| packages/…/calendar-recurring-event-wake-up.service.ts | Shows how future recurring calendar instances remain available. |
| packages/…/timeline-activity.service.ts | Shows how record changes become timeline history. |
| packages/…/widget.schema.ts | Shows the dashboard and page-layout widget model. |
| packages/…/create-complete-dashboard.tool.ts | Shows the workspace dashboard creation flow. |
| packages/…/get-dashboard.tool.ts | Shows how a dashboard returns its layout and readable widget context. |
| packages/…/update-page-layout-widget.tool.ts | Shows the shared widget update boundary for dashboards and record pages. |
| packages/…/message-campaign.service.ts | Shows campaign audience checks, variable validation, and queued sending. |
| packages/…/send-email.resolver.ts | Shows direct email sending and record-thread linking. |
| packages/…/workflow-run.workspace-entity.ts | Shows the workspace record used to track automation state. |
| packages/…/core-workflow-runner.service.ts | Shows how workflow definitions become queued workspace runs. |
| packages/…/run-workflow.job.ts | Shows how queued runs start, resume, retry, and end. |
| packages/…/workflow-run-job-scope.workspace-service.ts | Shows how workflow ownership maps to queue scope. |
| packages/…/assert-version-can-be-activated.util.ts | Shows the boundary that keeps invalid workflow versions inactive. |
| packages/…/CoreObjectRunInsightsOverview.tsx | Shows the shared run health summary used by workspace automation views. |
| packages/…/useCoreAgents.ts | Shows how agent records and recent run summaries form the agent list. |
| packages/…/CoreWorkflowOverviewTab.tsx | Shows the workflow health view with counts, failure rate, duration, and failed runs. |
| packages/…/workspace-member-delete-one.post-query.hook.ts | Shows cleanup and ownership transfer after member removal. |
| packages/…/getObjectColorWithFallback.ts | Shows the fallback visual identity for system, standard, and custom objects. |
| packages/…/View.ts | Shows the client view model for filters, groups, visibility, and calendar presentation. |