Records, views, and activity experiences
The CRM record experience turns workspace data into connected ways to work. Records hold business facts, metadata gives each object its shape, views organize records for a task, and activities show work and change around them. Dashboards combine these surfaces into focused pages. See CRM workspace for the wider workspace model and workspace members for member access and identity context.
Record model
Object records
An object record is one business item in a workspace. It has a stable identity, audit data, fields, and relations defined by its object. The same record can appear in a table, board, calendar, list, detail page, or dashboard widget.
Relations connect people, companies, opportunities, activities, and other records. A junction relation adds an intermediate record when the relationship needs its own data. A polymorphic relation can point to more than one object type. The record experience presents the terminal business records when a junction should stay hidden from the member.
References: packages/…/ObjectRecord.ts• L1-3 packages/…/resolveJunctionConfig.ts• L60-138 packages/…/isJunctionLikeObject.ts• L5-18 packages/…/isJunctionRelationForbidden.ts• L18-83
Object metadata
Object metadata defines how an object behaves in the workspace. It names the object, its fields and relations, its record label, and its links to views and permissions. Field metadata defines the value type, label, defaults, edit rules, relation target, and display choices. This lets one record experience support standard and custom objects.
Metadata also defines the write boundary. An object, record, or field is read-only when its source, permissions, relation target, or UI rules do not allow a change. Remote objects and objects that are not editable in the user interface stay read-only. A one-to-many relation also stays read-only when attaching or detaching it would require an update that the target object or inverse field does not allow. The same boundary applies in forms, inline cells, relation pickers, boards, calendars, and table widgets.
Field choices also have a life cycle. Inactive select choices are hidden from new selections but remain visible when a record already uses them. A new choice cannot reuse an existing label or derived value. This keeps older records readable without allowing new records to take stale or duplicate values.
References: packages/…/object-metadata.entity.ts• L41-87 packages/…/field-metadata.entity.ts• L68-129 packages/…/isObjectMetadataReadOnly.ts• L8-28 packages/…/isOneToManyRelationFieldReadOnlyDueToTargetUpdatePermission.ts• L20-86 packages/…/isRecordFieldReadOnly.ts• L21-57 packages/…/FieldMetadata.ts• L16-22 packages/…/filterSelectableFieldOptions.ts• L3-17 packages/…/isSelectOptionNameTaken.ts• L3-19
Record data selection
Each surface asks for the fields it needs instead of loading every field for every record. The selection covers identity, visible fields, filter and sort fields, group fields, and relation identifiers. Partial results merge into shared record state, so one surface can add data without erasing fields loaded by another.
Relation data follows the same rule. A normal relation can load identifiers or deeper target data. A junction relation expands only when its metadata is valid. A polymorphic relation keeps a stable field name for each readable target. A table lookup can add one readable, non-relation field from a related record. The table adds the related record to shared state so the lookup cell can use the same field rules as any other record field. Large result actions use cursor pages or offsets and report progress rather than requiring every record at once.
References: packages/…/generateDepthRecordGqlFieldsFromFields.ts• L17-166 packages/…/generateRecordCacheFragment.ts• L12-61 packages/…/getRecordFromCache.ts• L25-69 packages/…/updateRecordCache.ts• L14-60 packages/…/modifyRecordCache.ts• L7-33 packages/…/addLookupTargetsToRecordGqlFields.ts• L5-31 packages/…/getRecordsWithLookupRelatedRecords.ts• L10-41 packages/…/useLazyFindManyRecords.ts• L31-172 packages/…/useLazyFindManyRecordsWithOffset.ts• L22-110
Record values
Field values have matching display and input experiences. Composite fields keep related parts together, such as a phone number with country details or a currency amount with its currency code. Record forms and inline cells use the same metadata, so a field keeps one meaning across detail, list, table, and board surfaces.
Record creation and update accept only values that belong to the object. Editors validate select choices against row-level access rules and active validation rules. Inactive choices cannot be selected for a new value, but an inactive choice already on a record remains available so the member can understand or remove it. Date inputs keep a stable stored form while showing the member's time zone. Workflow record searches use UTC. Rich text keeps a current document form and can include mentions and files. Multi-record fields can hold fixed record IDs or workflow variables.
References: packages/…/FormFieldInput.tsx• L69-97 packages/…/FormFieldInput.tsx• L126-138 packages/…/SelectFieldInput.tsx• L26-87 packages/…/MultiSelectFieldInput.tsx• L14-67 packages/…/filterSelectableFieldOptions.ts• L3-17 packages/…/FormDateFieldInput.tsx• L117-247 packages/…/FormDateTimeFieldInput.tsx• L112-255
Record changes
Record changes update shared record state before the server responds when the result can be predicted. A failed create removes the temporary record. A failed update restores only the fields changed by that update. Batch creation follows the same pattern and refreshes summaries after the server confirms the new records.
The update path also emits a record operation event. Views that place records by field value can then return to the correct group after a failed change. Record chips use the object label rule and open the record in the configured page or side panel.
References: packages/…/useCreateManyRecords.ts• L94-259 packages/…/useUpdateOneRecord.ts• L85-167 packages/…/useUpdateOneRecord.ts• L188-307 packages/…/deleteRecordFromCache.ts• L9-41 packages/…/RecordChip.tsx• L45-118
Record defaults
Some records receive defaults from row-level access rules. These rules can use fixed values or values from the current workspace member. The create flow combines those defaults with view context before it sends the record. Composite fields keep their individual parts together.
The same rules can limit select choices and whether an empty value is allowed. The editor therefore does not offer values that the member cannot save.
References: packages/…/useBuildRecordInputFromRLSPredicates.ts• L112-225 packages/…/useFilteredSelectOptionsFromRLSPredicates.ts• L121-163 packages/…/useFilteredSelectOptionsFromValidationRules.ts• L40-75
Record surfaces
Record detail
Record detail is the focused surface for one object record. It shows fields and relations in a full page or side panel. It also provides the target record context for activities and page widgets. A deleted record stays visible as deleted so its state is clear.
Record pages now use the page-layout experience. The record remains the target context for the layout, while the side-panel footer provides record actions where the surface supports them. Relation fields show only readable targets. A relation item can expand the target record, detach it, or delete it when the relevant permissions allow those actions.
References: packages/…/RecordShowPageShell.tsx• L17-127 packages/…/PageLayoutRecordPageRenderer.tsx• L43-115 packages/…/useDisplaySidePanelFooter.ts• L7-30 packages/…/RecordDetailRelationRecordsListItem.tsx• L167-289 packages/…/categorizeRelationFields.ts• L58-95
Record index
The record index is the shared entry point for browsing one object. Members can search, select records, edit many records, merge records, import records, and export the current result. These actions use the active metadata and view rules, so bulk work keeps the meaning of composite and relation fields.
Selection belongs to the records currently displayed. Search and pickers exclude records the member cannot read. A relation that allows several object types can search across the readable types while retaining already selected records. Fields or relation labels that are not readable remain safe and do not expose their values.
The index does not render a record surface when the member has no readable records. Empty results distinguish no match, no data, deleted records, remote data, and no create access. List rows allow drag reorder only when the member can update records. Exports use the active query and canonical visible fields, so an extra table-only lookup column does not duplicate the source field.
Record queries are permission-gated before they run. Cursor pages, lazy queries, offset queries, and combined searches use the same boundary. Combined searches omit object types for which the member has no readable records. Record-level sharing adds a direct-record path for shareable objects without making the whole object readable.
References: packages/…/RecordIndexContainerGater.tsx• L35-127 packages/…/getEmptyStateTitle.ts• L4-13 packages/…/useRecordIndexExportParameters.ts• L71-143 packages/…/RecordListDraggableRow.tsx• L36-89 packages/…/useFindManyRecords.ts• L39-153 packages/…/useLazyFindManyRecords.ts• L31-172 packages/…/useLazyFindManyRecordsWithOffset.ts• L22-110 packages/…/useGenerateCombinedFindManyRecordsQuery.ts• L20-141 packages/…/useCanReadObjectRecordsOrSharedRecords.ts• L8-29
Record search and pickers
Record search supports both direct record browsing and relation selection. Single and multi-record pickers restrict searchable object types by read access, keep selected items visible during a new search, and page through results. A picked record can come from an object type that is not in the current unselected result set.
Morph relation inputs apply the same rule to several target object types. If a selected target is no longer readable, the form shows a safe forbidden state instead of exposing its label or allowing a new link. A junction relation is also forbidden when its intermediate record or all of its readable terminal targets are unavailable.
References: packages/…/useSingleRecordPickerPerformSearch.ts• L22-189 packages/…/useMultipleRecordPickerPerformSearch.ts• L30-391 packages/…/useMultipleRecordPickerPerformSearch.ts• L394-485 packages/…/FormMorphRelationToOneFieldInput.tsx• L74-181 packages/…/isJunctionRelationForbidden.ts• L18-83
Record forms
Creation and update forms provide a shared way to finish a record when inline editing is not enough. A create request opens a side-panel form with an initial draft and can keep the form open for another record. An update request can move to a side-panel form when active validation rules require fields that the current edit did not include.
The update flow checks that fields read by a validation rule are loaded before it asks for completion. It sends only fields that are eligible and writable. Date fields support member-time-zone display and workflow variables. Canceling a form returns no change, while completion returns the extra fields to the original record action.
References: packages/…/RecordCreationFormProvider.tsx• L41-200 packages/…/RecordUpdateFormProvider.tsx• L34-129 packages/…/useCompleteRecordUpdate.ts• L69-178 packages/…/computeRecordUpdateFieldsToComplete.ts• L14-92 packages/…/FormDateFieldInput.tsx• L81-331 packages/…/FormDateTimeFieldInput.tsx• L75-331
Record views
View purpose
A view is a saved way to inspect one object. It combines visible fields, filters, sorts, groups, aggregates, and a layout. The layout selects a table, board, calendar, or list experience. The rules select the records and order shown in that experience.
The server resolves a view only when it is available to the member. It then resolves current object and field metadata into a permission-aware record query. A view is therefore a reusable product rule, not only a visual preference. Unlisted view changes remain limited to the owner. Grouped table and list views can also save whether groups appear as sections or as tabs.
References: packages/…/view.entity.ts• L91-124 packages/…/view.entity.ts• L213-251 packages/…/view.service.ts• L326-391 packages/…/view-query-params.service.ts• L52-188 packages/…/is-view-available-to-user.util.ts• L1-20 packages/…/is-view-visible-to-user.util.ts• L1-20
Filter rules
Filters select records by field value. A filter group joins rules with AND or OR logic, and groups can nest. Filters can use composite subfields, related record fields, relation IDs, dates, actors, countries, currencies, activity sources, or fields from a parent relation.
The filter editor chooses its value control from current field metadata. A relation filter can move from the source relation to a readable target field. The target field supplies the filter type, operand, label, and value control. If saved metadata no longer resolves, the filter stays unresolved instead of silently changing meaning. Relative dates use the member's time zone in normal views. Workflow record searches use UTC so their date syntax stays stable across locales.
Actor filters can represent named workspace members or the current member. The index can also add a deleted-record filter. This keeps deleted records out of normal views and lets a member inspect them only when the view asks for them. Local filter matching follows the server's relation rules, so an unfetched value does not become a match only because a filter is negated.
References: packages/…/useApplyAdvancedFilterRelationTargetField.ts• L25-124 packages/…/filterValueFieldMetadataItemUsedInDropdownComponentSelector.ts• L10-34 packages/…/ObjectFilterDropdownContentWrapper.tsx• L9-35 packages/…/isRecordMatchingFilter.ts• L136-534 packages/…/useFindManyRecordIndexTableParams.ts• L24-109 packages/…/RecordIndexEmptyState.tsx• L43-111
View layouts
Table views support dense field work. List views support a vertical scan. Board views group records into columns. Calendar views place records on dates and support day, week, and month ranges. All layouts open the same record detail experience.
A board needs a usable grouping field. A calendar needs a usable date or date-time field. The default view does not offer board layout. Saved views can switch between table, list, board, and calendar when their metadata supports the choice. Calendar views save their date field and range. Non-table and non-list views can also use compact mode. Widget views use separate layout types so they do not appear as normal record-index choices.
Board and calendar cards expose the visible fields as inline record cells. Extra fields, such as lookup columns, are table-only. Other layouts use one entry per field metadata. The same read-only and restricted-field rules apply there as in the table and detail surfaces. List rows show populated visible fields within the available row width and open the same record detail when selected.
References: packages/…/ObjectOptionsDropdownLayoutContent.tsx• L43-131 packages/…/ObjectOptionsDropdownLayoutContent.tsx• L152-351 packages/…/isRecordFieldSupportedByViewType.ts• L5-12 packages/…/isRecordGroupTabsSupportedForViewType.ts• L4-12 packages/…/RecordBoardContext.ts• L1-80 packages/…/RecordCalendarContext.ts• L1-80 packages/…/RecordBoardCardBody.tsx• L24-136 packages/…/RecordCalendarCardBody.tsx• L30-145 packages/…/RecordListRow.tsx• L121-237
View fields and groups
Members can show, hide, search, and reorder fields in a view. These choices control the columns or card fields used by the layout. The label field remains available as the record identity even when other fields are hidden. A view can mark a field as unavailable when the field itself or its relation label is not readable.
Table views can add a lookup field. A lookup shows one readable, non-relation field from a related record. It keeps the source relation as its path, but uses the target field's label and value rules. Lookup fields are extra table columns rather than a second copy of the source field. They are not available in widget views, which save their columns by field metadata.
Grouped views can control the grouping field, group order, empty-group visibility, and load limit. Group summaries use the active filters and visible group choices. A board group can create a record with its group value prefilled when the field is writable.
Table and list views can display the groups as tabs. The tabs include an All groups choice and the visible groups, while overflow groups move to a more menu on wide screens. Selecting a group applies that group filter and resets record selection. Group counts and aggregate summaries follow the active filters and permissions. Grouped sections load more records as needed and fall back to a manual action after an automatic load fails.
Table headers also give members a direct way to filter, sort, move, hide, reorder, and resize visible fields. These changes update the saved view field contract. A table widget in page-layout edit mode keeps such changes in its draft until the page layout is saved. A live widget does not write view metadata on its own.
View sorting uses field metadata. A relation sort follows the target label field when that metadata is available. If no saved sort controls a local object, its position can provide the final order. Remote objects do not receive that local fallback. A sort blocks manual reorder until the member removes it.
When a board group has a non-manual sort, a member must confirm before changing the group order by hand. Confirmation changes that group sort to manual so the saved order matches the member's action. List row dragging follows the same update permission boundary.
References: packages/…/getRecordFieldLookupTarget.ts• L11-63 packages/…/getLookupTargetFieldMetadataItems.ts• L5-23 packages/…/RecordTableCellLookupFieldContext.tsx• L23-85 packages/…/useCanAddRecordTableLookupColumns.ts• L7-21 packages/…/RecordGroupTabs.tsx• L95-181 packages/…/getActiveRecordGroupTabId.ts• L4-22 packages/…/useRecordIndexGroupsAggregatesGroupBy.ts• L61-143 packages/…/RecordTableColumnHeadDropdownMenu.tsx• L74-139 packages/…/RecordTableHeaderDnd.tsx• L17-66 packages/…/useResizeTableHeader.ts• L182-239 packages/…/useDeleteRecordTableColumn.ts• L10-78 packages/…/view-field.entity.ts• L27-119
View aggregates
Views can summarize records by group or table column. The member chooses an operation supported by the field, such as count or a value summary. Relations support counts. Number, rating, currency, boolean, and date fields expose the summaries that fit their type. The result follows the active filters and group context. Record changes refresh matching summaries.
In a table, the aggregate footer is part of the view field experience. It shows the current result or lets the member choose an operation that the field supports. A page-layout widget keeps a draft aggregate choice in the widget view until the layout is saved. Invalid field and operation pairs do not produce an aggregate query. Date minimum and maximum values are presented as earliest and latest.
References: packages/…/useAggregateRecords.ts• L23-85 packages/…/generateGroupsRecordsGroupByQuery.ts• L12-60 packages/…/useRecordIndexGroupsAggregatesGroupBy.ts• L68-143 packages/…/getAvailableAggregationsFromObjectFields.ts• L18-103 packages/…/RecordTableAggregateFooter.tsx• L51-86 packages/…/useViewFieldAggregateOperation.tsx• L18-101
View lifecycle
Members can create a view from the current record context, change its layout and rules, reorder it, favorite it, share it with the workspace, or keep it unlisted. The default view cannot be deleted. A custom view can be deleted only when another view remains.
View changes use one metadata contract for the picker and the active surface. Local changes can appear first and return to the last accepted state when the server rejects them. Complete saves replace only child lists that are present, so an omitted list remains unchanged. Group display, visible groups, and group limits are part of the saved view contract when the selected layout supports them. Widget view updates use the same contract for fields, filters, groups, and sorts, but accept only widget layout types.
The relationship between metadata, a view, and a record surface is shown below.
flowchart LR
Metadata[Object and field metadata] --> View[Saved view]
View --> Rules[Fields, filters, sorts, groups, and aggregates]
Rules --> Surface[Table, board, calendar, or list]
Surface --> Records[Object records]
Records --> Detail[Record detail and activity surfaces]
References: packages/…/create-view-field.input.ts• L14-69 packages/…/view-field.service.ts• L40-220 packages/…/view-widget-upsert.service.ts• L96-237 packages/…/view-widget-upsert.service.ts• L271-446 packages/…/create-view.input.ts• L31-144 packages/…/update-view.input.ts• L32-138 packages/…/RecordIndexContainer.tsx• L34-80 packages/…/view.service.ts• L50-219
Activity experiences
Notes, tasks, and files
Notes and tasks are activity records attached to a target record. Notes preserve written context and files. Tasks represent planned work with an assignee, status, due date, and position. Shared activity cards let the same work appear on a record page or dashboard widget.
Record pages keep activities separate from the main object fields. Notes support rich text and attachments. Tasks support grouping, filtering, completion, overdue dates, and target changes.
References: packages/…/note.workspace-entity.ts• L9-18 packages/…/task.workspace-entity.ts• L10-23 packages/…/ActivityList.tsx• L5-39
Calendar events
Calendar events connect a time-based meeting to one or more records. An event can include a title, time range, time zone, guests, location, description, invitations, and a conference link. The composer starts from the record that opened it and can add other readable targets.
The calendar service creates the event first. The workspace then creates record links and refreshes calendar activity data. A link failure is reported separately because retrying the whole action could create a duplicate event. Members can also search existing events and toggle their link to the current record. The link picker separates events already related to the current record from other events.
sequenceDiagram
participant Composer as Event composer
participant Calendar as Calendar service
participant Links as Record links
participant Timeline as Record timeline
Composer->>Calendar: Create event
Calendar-->>Composer: Return event result
Composer->>Links: Attach selected records
Links-->>Composer: Confirm links
Composer->>Timeline: Refresh calendar activities
References: packages/…/CalendarEventComposerFields.tsx• L82-260 packages/…/useCalendarEventComposer.ts• L99-190 packages/…/useCreateCalendarEvent.ts• L22-59 packages/…/LinkCalendarEventsDropdown.tsx• L20-55 packages/…/LinkActivitiesDropdownContent.tsx• L64-141 packages/…/useToggleActivityLink.ts• L41-97
Email communication
Email communication brings email and app-based message threads into record activity surfaces. A thread keeps its identity, subject, body, participants, time, draft state, channel, and sharing state. A member can open full content only when its share level permits it. Restricted content uses a safe unavailable state.
Recipient selection connects email to the record model. Related people are suggested first in company, person, and opportunity contexts. Sending can use a connected account or an app message channel. Successful sends refresh the record's thread and channel data. A channel filter lets members focus a record's conversations by provider or installed application. Channel labels and icons use workspace application metadata so built-in and custom channels remain clear.
The composer keeps a draft for the active context and shows each submitted message while it is pending. A failed message stays available for retry or discard. On success, the composer refreshes thread data and removes the pending message when refresh succeeds. If refresh fails, it marks the message sent locally so the member does not retry a message that may already have been delivered. Attachments upload before an app message is sent, and a stable idempotency key prevents a retry from delivering the same message twice. A disconnected channel blocks sending and offers reconnect when the member has access.
Campaigns extend the same model to a selected audience with a sender, schedule, body variables, delivery state, and counts. A sent campaign shows its body in a read-only preview.
References: packages/…/EmailThreadMessage.ts• L4-15 packages/…/EmailsCard.tsx• L18-81 packages/…/getTimelineThreadsFromObjectRecord.ts• L4-23 packages/…/getTimelineThreadChannelsFromObjectRecord.ts• L3-17 packages/…/timelineThreadChannelFilterFamilyState.ts• L1-10 packages/…/getMessageChannelLabel.ts• L8-38 packages/…/ChatThreadComposer.tsx• L75-221 packages/…/useSendPendingChatMessage.ts• L16-72
Timeline activities
A timeline activity is a dated history item linked to a target record. It can describe a record change, note, task, email message, calendar event, or linked object. The timeline joins these sources into one history for the record.
The timeline filters by activity type, groups entries by month, and loads more entries as the member reaches the end. It resolves linked records through current permissions. Change entries show before and after values for readable fields. Hidden or deleted records use an empty value or safe identifier.
References: packages/…/timeline-activity.workspace-entity.ts• L17-50 packages/…/TimelineActivity.ts• L4-29 packages/…/TimelineCard.tsx• L39-93
Dashboards and page experiences
Dashboard composition
A dashboard is a named workspace page that uses a page layout. The layout arranges record tables, timelines, notes, tasks, relation fields, rich text, charts, and other record-focused widgets. Widgets reuse the same record and activity data as record pages rather than creating a second data model.
Page layout widgets are metadata. The server validates field references, nested relations, and rich text before it saves them. Dashboard tools can create and read dashboards and manage their tabs and widgets within the workspace permission context.
Widget field references must resolve to active field metadata. An inactive field therefore cannot continue to drive a saved widget.
References: packages/…/dashboard.workspace-entity.ts• L8-16 packages/…/PageLayoutWidget.ts• L4-16 packages/…/page-layout-widget.service.ts• L102-157 packages/…/find-active-flat-field-metadata-by-id.util.ts• L8-32 packages/…/create-complete-dashboard.tool.ts• L56-229
Record widgets
A record table widget uses an object and a view as its data contract. It can show that view as a table, board, list, or calendar inside a page. Layout editing can use a draft view. The saved view remains unchanged until the layout is ready.
The widget uses the view's fields, filters, sorts, groups, aggregates, and layout together. A widget without readable records does not expose a record surface. Widget creation can add a related record or create a nested target when relation metadata and permissions allow it.
References: packages/…/RecordTableWidgetRendererContent.tsx• L37-96 packages/…/RecordTableWidgetProvider.tsx• L43-195 packages/…/RecordTable.tsx• L24-118 packages/…/widget.schema.ts• L570-583
Chart widgets
Chart widgets turn filtered record data into visual summaries. Bar and line charts group by metadata fields, apply an aggregate and filter, and use date granularity with the member's time zone and locale. Relation labels follow the same access rules as record labels.
Supported date ranges and select options receive zero-valued entries for missing groups. “Not set” groups stay separate. Invalid chart inputs and denied queries return chart-specific errors so the page can show a useful failure without exposing data.
References: packages/…/bar-chart-data.service.ts• L50-217 packages/…/line-chart-data.service.ts• L51-227 packages/…/chart-relation-label.service.ts• L39-104 packages/…/fill-date-gaps.util.ts• L21-90 packages/…/fill-select-gaps.util.ts• L11-50
Relation widgets
Relation widgets show a bounded set of records linked to the current target. They can expand a related record, edit it when allowed, show more loaded records, or open the related object's index with a filter for all records linked to the target. A permission-aware count distinguishes the loaded slice from the full relation.
References: packages/…/FieldWidgetRelationRecordsCard.tsx• L74-147 packages/…/useFieldWidgetRelationRecordsTotalCount.ts• L21-91 packages/…/useFieldWidgetRelationSeeAllHref.ts• L13-58
Activity widgets
The timeline widget reuses the target-record timeline card. Notes and tasks use activity cards that let a dashboard show history, written context, or planned work as separate areas. Campaign composition can also occupy one widget while keeping campaign details and message content together.
References: packages/…/TimelineWidget.tsx• L1-12 packages/…/NoteWidget.tsx• L1-80 packages/…/TaskWidget.tsx• L1-80 packages/…/CampaignWidgetContainer.tsx• L4-11
Dashboard lifecycle
Dashboards can be duplicated through the REST and GraphQL workspace APIs. Duplication copies the page layout and then creates a dashboard record that points to the copied layout. The operation checks dashboard creation access before copying and removes the layout if dashboard creation fails.
Dashboard tools use the same page, tab, widget, position, metadata, and workspace services as the normal dashboard flow. Object and field names can resolve to metadata IDs for tool-created widgets. This keeps tool-created dashboards subject to the same workspace boundaries as member-created dashboards.
References: packages/…/dashboard.controller.ts• L15-46 packages/…/dashboard.resolver.ts• L17-51 packages/…/dashboard-duplication.service.ts• L50-167 packages/…/create-complete-dashboard.tool.ts• L124-279
Page layout controls
Page layouts are configurable workspace metadata. Members can change tabs and widget positions, hide widgets for the current context, reset a widget or tab, and reset the full layout. Saving a layout also makes needed widget views available to the persisted page.
Widget visibility depends on context. Full pages, side panels, and mobile devices can use different visibility rules. A selected target record can shape relation and activity widgets without changing the underlying record model.
References: packages/…/useUpdatePageLayoutWidgets.ts• L15-79 packages/…/useSavePageLayout.ts• L55-96 packages/…/useResetPageLayoutToDefault.ts• L15-58
Record sharing
Record access
Record sharing adds access for a workspace member, role, or everyone with workspace access. A share has an access level such as none, read, read-write, or full. On shareable non-system objects, a direct record grant can let a member read a record even when their role cannot read the object.
The resulting permission still combines object, field, inherited, and relation-target rules. Private state changes how general access appears. The sharing experience separates general access from named recipients and does not offer a recipient who already has access. Direct sharing changes the record query path only for eligible shareable objects.
References: packages/…/recordSharingFragment.ts• L3-29 packages/…/useRecordSharing.ts• L19-133 packages/…/getRecordSharingGeneralAccess.ts• L5-21 packages/…/useCanReadObjectRecordsOrSharedRecords.ts• L8-29
Workspace relationships
Record visibility and activity ownership depend on workspace context. Object and field metadata determine which records and fields a member can use. Record sharing can add direct access, but role, field, inherited, and target-relation rules still apply. View visibility determines which saved views a member can select, while activities identify the member who caused or owns the work.
Change checklist
When these files or sections are changed, remember to consider these:
- When object or field metadata changes, review record field selection, cache fragments, relation identifiers, lookup targets, picker targets, view fields, filters, grouping, aggregates, exports, forms, and dashboard widget references together.
- When permission or read-only handling changes, review index gating, safe labels, detail fields, inline cells, table rows, board cards, calendar cards, lookup cells, relation pickers, select choices, relation attach or detach actions, and create controls together.
- When record cache or mutation behavior changes, review partial record merging, related lookup records, optimistic rollback, relation placement, aggregate refresh, pagination cursors, virtualization, and drag or group state together.
- When filter persistence or matching changes, review composite subfields, relation target fields, actor values, unloaded values, unresolved metadata, deleted-record filters, server query meaning, direct inputs, and workflow time zones together.
- When view field behavior changes, review canonical fields, extra lookup columns, table-only support, widget view limits, field export selection, column deletion rollback, and view-field metadata persistence together.
- When view layout or group behavior changes, review table, list, board, calendar, default-view limits, calendar fields, compact mode, group summaries, manual sorting, relation-label sorting, group reorder confirmation, group visibility, group tabs, active-tab fallback, virtualization, and widget draft views together.
- When form validation changes, review loaded relation data, eligible writable fields, select option filtering, date and date-time zones, morph targets, completion and cancellation state, and inline persistence together.
- When activity visibility or send state changes, review record links, protected thread and event content, attachments, campaign draft state, sent previews, pending message state, retry and discard behavior, and timeline refresh together.
- When dashboard lifecycle changes, review layout duplication, pending widget views, chart and rich text validation, active field references, relation counts, target-record context, API access, tool permissions, partial widget results, and layout reset behavior together.
- When role or object permission changes, review the read-before-write rule, record index gating, picker search, combined object searches, direct record sharing, relation target access, and widget visibility together.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A partial response replaces shared record state | Another surface loses fields it already loaded | Merge selected fields into the shared cache and record store |
| A lookup target field is inactive, unreadable, or a relation | The table shows a stale or unsafe related value | Offer only active readable non-relation target fields and apply target-field restrictions |
| A member has no readable records | A surface can expose an unusable index or picker | Gate the surface and show a permission-aware empty state |
| A relation target is readable but not writable | A member can select a target that cannot be linked or created | Build target choices from current read and update permissions |
| A saved filter refers to missing metadata | The view can change meaning or fail to query | Rebuild labels and types from current metadata and keep unresolved filters separate |
| A selected picker record is outside the new search set | The selected item disappears or loses its label | Search selected IDs separately and retain them in the result |
| A morph target or junction path is not readable | A relation field exposes an unsafe label or link | Show a forbidden state and exclude unreadable target paths |
| A sort remains active during manual reorder | Record order no longer matches the saved sort | Block reorder or require the member to remove the sort |
| A board group is reordered while a non-manual sort remains active | The saved group order can conflict with the active sort | Require confirmation and switch the group sort to manual |
| A grouped table or list view uses a hidden or stale group tab | The active tab can show the wrong records or stale counts | Derive the active tab from visible group IDs and reset selection when it changes |
| A group page loads more records after an automatic request fails | The surface can retry in a loop or hide the recovery action | Stop automatic retries and show a manual Load more action |
| An update needs fields that are not loaded for a validation rule | The record can be checked against incomplete data | Fetch the needed record and relations before asking for form completion |
| A board or calendar change uses the wrong writable field | The record moves visually but is not saved in the intended group or date | Require a valid grouping or date field and apply the member time zone |
| A workflow date filter uses the member time zone | The same workflow can select different records by locale | Use UTC for workflow record searches |
| An event is created but record linking fails | The event exists but is absent from the target timeline | Report link failure separately and do not blindly retry event creation |
| A restricted event or email thread opens as shared | Protected activity content is exposed | Gate content and panel opening on the allowed share level |
| A channel filter has no matching conversations | The email surface can look broken even though other threads exist | Show a filter-specific empty state and let the member clear the channel filter |
| A message is retried without a stable send key | The same app message can be delivered more than once | Reuse the pending message or composer idempotency key for retries |
| A message succeeds but thread refresh fails | The composer can prompt a duplicate retry for a message that may already exist | Mark the pending message as sent locally and refresh the thread through a later action |
| A connected message channel is unavailable | The composer can accept input that cannot be sent | Disable sending and show the reconnect path when allowed |
| A chart relation-label query ignores permissions | A chart exposes a related label or fails as unscoped data | Resolve labels in the member's permission context |
| A role receives record write access without record read access | The member can be granted an unusable write path | Reject the permission change unless read access is also granted |
| A dashboard widget points to an inactive field | The page can show a broken or stale field reference | Resolve widget fields against active metadata before saving |
| Dashboard insertion fails after layout creation | An unused page layout remains | Remove the copied layout when dashboard creation fails |
Key files
| File | Why to read it |
|---|---|
| packages/…/object-metadata.entity.ts | Defines the object-level record model and its links to fields and permissions. |
| packages/…/field-metadata.entity.ts | Shows how fields define values and relations. |
| packages/…/generateDepthRecordGqlFieldsFromFields.ts | Shows how relation and field metadata shape record data. |
| packages/…/getRecordFieldLookupTarget.ts | Shows the product boundary for table lookup fields. |
| packages/…/RecordTableCellLookupFieldContext.tsx | Shows how lookup values use related-record field and permission rules. |
| packages/…/generateRecordCacheFragment.ts | Shows how metadata and permissions shape shared record data. |
| packages/…/useCreateManyRecords.ts | Shows the shared create and rollback experience for batch record creation. |
| packages/…/useFindManyRecords.ts | Shows permission-gated record queries and the normal versus deleted-record query boundary. |
| packages/…/useUpdateOneRecord.ts | Shows optimistic updates, rollback, event dispatch, and aggregate refresh. |
| packages/…/RecordIndexContainerGater.tsx | Connects object permissions to the record index surface. |
| packages/…/useRecordIndexExportParameters.ts | Connects active view state to record export fields and filters. |
| packages/…/useFindManyRecordIndexTableParams.ts | Connects filters, group filters, sorts, and group limits to the record query. |
| packages/…/useMultipleRecordPickerPerformSearch.ts | Shows permission-aware multi-object search and selected-item retention. |
| packages/…/useCompleteRecordUpdate.ts | Shows how validation can move an update into a completion form. |
| packages/…/useApplyAdvancedFilterRelationTargetField.ts | Shows relation traversal from a source field to a target field in a filter. |
| packages/…/isRecordMatchingFilter.ts | Shows how local filter matching follows relation and field metadata rules. |
| packages/…/view.entity.ts | Defines the saved view contract, including layouts, groups, visibility, and group display. |
| packages/…/view-query-params.service.ts | Shows how a saved view becomes a permission-aware record query. |
| packages/…/view-field.entity.ts | Defines canonical fields, extra fields, aggregates, and lookup targets in a view. |
| packages/…/view-widget-upsert.service.ts | Shows how widget-specific view fields, filters, groups, and sorts are saved. |
| packages/…/ObjectOptionsDropdownLayoutContent.tsx | Shows the layout choices and their required fields. |
| packages/…/ObjectOptionsDropdownRecordGroupsContent.tsx | Shows the group, visibility, sorting, and load-limit choices. |
| packages/…/RecordGroupTabs.tsx | Shows grouped table and list navigation and selection reset. |
| packages/…/useDeleteRecordTableColumn.ts | Shows safe column removal and rollback when view-field persistence fails. |
| packages/…/useViewFieldAggregateOperation.tsx | Shows how table aggregate choices use the live view or a page-layout draft. |
| packages/…/useCalendarEventComposer.ts | Shows event creation, record linking, and timeline refresh. |
| packages/…/LinkActivitiesDropdownContent.tsx | Shows how existing activities are searched and linked to a target record. |
| packages/…/EmailsCard.tsx | Shows channel-filtered thread loading and timeline refresh behavior. |
| packages/…/ChatThreadComposer.tsx | Shows drafts, attachments, pending sends, retry, discard, and post-send refresh behavior. |
| packages/…/useSendPendingChatMessage.ts | Shows attachment upload and idempotent retry for pending messages. |
| packages/…/TimelineCard.tsx | Shows the target-record timeline experience. |
| packages/…/RecordTableWidgetRendererContent.tsx | Connects dashboard record widgets to views. |
| packages/…/RecordTableWidgetProvider.tsx | Shows widget permission gating and draft-view context. |
| packages/…/find-active-flat-field-metadata-by-id.util.ts | Shows the active-field boundary for page layout widgets. |
| packages/…/bar-chart-data.service.ts | Shows metadata-driven chart grouping and aggregation. |
| packages/…/dashboard-duplication.service.ts | Shows permission-aware dashboard duplication and rollback. |
| packages/…/useCanReadObjectRecordsOrSharedRecords.ts | Shows the read path for direct record sharing. |