A view is Jetstack's configured data workspace for a type. It combines:
- a target object type
- a default query
- a default viewer
- runtime display options
- add-time context rules
- query switching options
- optional folder context
- view-level actions
- per-viewer layout settings
In practical terms, a view is the place where a type and a query become a usable interface.
Types define what data exists. Queries define which records and columns are relevant. Views decide how that result becomes a working screen.
Use views to shape different jobs around the same data model. For example, the same Task type can support:
- a table view for back-office review
- a kanban view for operational triage
- a calendar view for planning
- a card view for mobile-friendly inspection
A strong view reduces friction by making the right data, controls, and creation defaults appear in the right context.
This chapter follows the structure of the actual View builder in the platform:
- general configuration
- display and behavior settings
- add-time context injection
- view actions and layout configuration
- system fields
For each option, the goal is to explain:
- what it controls
- how it can be configured
- when to use it
- what effect it has at runtime
Use this chapter together with:
Keep these distinctions clear:
object_type defines which type the view works withquery defines the default data selectionviewer defines the default presentation moderelevant_queries defines which other queries users may switch to from this viewadding_* fields define how object creation behaves specifically from this viewview_actions define extra operations available from the viewsettings stores layout-builder configuration and viewer-specific layout state
The view is not the place to encode all business filtering logic. Put durable data-selection logic into Queries, then use the view to decide how that query becomes an interface.
The platform organizes view configuration into these groups:
- General
- Settings
- Adding
- System
There are also two important builder actions outside the standard field groups:
Layout builderActions editor
Those two are part of real view configuration even though they are not edited as plain scalar fields.
What it is:
- the main administrative name of the view
How to configure it:
- enter a stable, recognizable name such as
All Tasks, Open Opportunities, My Calendar, or Files By Project
Why it matters:
- this is the title-role field for the view resource
- it is used as the primary name in builder screens
- it also becomes the fallback heading when
view_title is empty
Use it when:
- you need a clean implementation-facing name that clearly describes the purpose of the view
Good practice:
- name views after the job they support, not only the type they display
- prefer
Invoices Awaiting Approval over just Invoices
What it is:
- the display-facing heading title of the view
How to configure it:
- enter the exact title users should see when the view renders
- leave it empty if the same wording as
view_name is appropriate
Why it matters:
- at runtime, Jetstack falls back to
view_name when view_title is empty
- this lets you keep a technical or administrative builder name while still presenting a cleaner end-user heading
Use it when:
- the displayed heading should differ from the internal builder name
- the user-facing wording should be shorter or more task-oriented
What it is:
- the icon associated with the view
How to configure it:
- choose an icon that reflects the work surface, such as list, board, calendar, files, or reporting
Why it matters:
- the icon strengthens navigation and recognition
- it also helps differentiate several views that target the same type
Use it when:
- the tenant uses multiple views of the same type and needs clear visual distinction
What it is:
- the type whose objects the view displays
How to configure it:
- select one type from the list of types
- the selected type should match the query and the intended viewer behavior
Why it matters:
- this is one of the foundational view settings
- it determines which properties, queries, actions, folder roots, and add-time values make sense
Runtime implications:
- the view loads objects of this type
- property references in
custom_col_names, adding_*, calendar mappings, and many layout settings are interpreted against this type
Design guidance:
- configure the type first or at least decide it early
- changing
object_type later can invalidate column mappings, add-value maps, or related query assumptions
What it is:
- the default viewer mode for the view
How to configure it:
- choose one of the supported viewer types, typically:
tabletable_sortablelistcardscalendarkanban
Why it matters:
- it determines how results are presented when the view first opens
- it influences which layout zones and layout components are meaningful
Important runtime rule:
- if the selected query is a custom query, the effective runtime viewer is always
table
- this means the configured
viewer is ignored for custom-query execution
Use each viewer when:
table: general-purpose tabular inspectiontable_sortable: table view with sortable behavior when that interaction matterslist: compact operational browsingcards: visual item scanningcalendar: date-oriented planningkanban: stage or workflow progression
Practical guidance:
- choose the viewer that matches the job, not only the data shape
- if users should switch viewers at runtime, configure the alternate viewer layouts in the layout builder as well
What it is:
- a manual property mapping for the calendar start date field
How to configure it:
- this field only appears when
viewer = calendar
- enter the target property reference using the type's property identifier, typically a system name or property ID
Why it matters:
- by default, Jetstack tries to infer the calendar start field from property roles such as start date or special date roles
- this field overrides that inference
Use it when:
- the type has several date-like properties
- the automatic role-based choice would be ambiguous
- the calendar should use a date field that is not the default role-based candidate
Example:
- a task type has
created_on, due_date, and planned_start
- the calendar should place items by
planned_start
- configure
explicit_start_property instead of relying on automatic inference
What it is:
- a manual property mapping for the calendar end date field
How to configure it:
- this field only appears when
viewer = calendar
- enter the property reference that should act as the calendar end field
Why it matters:
- it overrides the normal date-end role lookup
- it is especially useful for range-based items such as events, bookings, or planned work blocks
Use it when:
- the calendar should show duration rather than a single point in time
- the end field is not the obvious default
What it is:
- the default query for the view
How to configure it:
- select the query that should load when the view opens
- make sure the query targets the same
object_type
Why it matters:
- this is the view's baseline data definition
- the query controls filters, visible columns, groupings, calculations, merging, and result shape
Runtime behavior:
- the view stores the chosen query as its default
- users may still switch to other queries listed in
relevant_queries
- user-specific query preference may later override the active default in day-to-day use
Best practice:
- choose a query that represents the most common or safest starting point for the view
What it is:
- a grouping persistence flag for query switching
How to configure it:
- enable it when the view should preserve default fixed groupings from its main query even after switching to another query in the same view
Why it matters:
- a view can expose several relevant queries
- when a user switches away from the default query, Jetstack normally changes to the new query's grouping model
- with this option enabled, fixed default groupings from the main query remain active when the runtime merges query parameters
Use it when:
- the view's main structure depends on one stable grouping concept
- the query selector should change filters or scope without collapsing the grouping layout
Typical example:
- a kanban-like work view groups by status
- you want users to switch between
All, Mine, and Overdue
- the grouping by status should remain stable across those switches
What it is:
- additional queries users may switch to from this view
How to configure it:
- select one or more queries that belong to the same object type and make sense in the same working context
Why it matters:
- this turns one view into a reusable work surface with several query perspectives
- the runtime presents the default query together with these relevant alternatives
Runtime behavior:
- the default
query is always the baseline
relevant_queries are added as switchable options- availability is still filtered by query publicity and ownership rules
Use it when:
- users need several filters of the same operational screen
- you want one view to host
All, Mine, Team, Archived, or similar perspectives
Avoid it when:
- each query really deserves its own separate workflow and presentation
What it is:
- the activation switch for the view
How to configure it:
- keep it enabled for live views
- disable it when the view should remain stored but not actively used
Why it matters:
- this is the basic operational lifecycle flag
Use it when:
- staging a future view
- temporarily retiring a view without deleting it
- keeping draft or backup views out of normal use
¶ Display And Runtime Settings
What it is:
- whether the view heading should be rendered
How to configure it:
- enable it for normal standalone views
- disable it when the heading would be redundant, especially in embedded or canvas-driven contexts
Why it matters:
- views can be rendered directly or inside other surfaces
- a repeated title can make embedded compositions feel cluttered
Use it when:
- the view is the main surface on the page
Disable it when:
- the surrounding canvas or module already provides the section heading
What it is:
- whether the filters area should be shown by default
How to configure it:
- enable it when users should actively explore, narrow, or shape the result set
- disable it for intentionally fixed or simplified views
Why it matters:
- the filters area is where users access query switching, ad hoc filters, grouping, calculations, and related tools
Practical note:
- even when disabled, some runtime states may still surface filter-related information when active parameters exist
- the option controls the primary visibility intent of the view
Use it when:
- the view is exploratory or analytical
Disable it when:
- the view is meant to behave like a fixed dashboard or tightly scoped task surface
What it is:
- whether the standard object creation button should be shown
How to configure it:
- enable it if this view should be a creation entry point
- disable it if objects should not be created from this context
Why it matters:
- the view can double as both browsing surface and context-aware creation surface
Important runtime rule:
- the button is only shown if the user is allowed to create objects of the selected
object_type
- this means enabling the flag does not bypass permissions
Use it when:
- the view naturally leads to creating more objects of the same type
Disable it when:
- records should be created only through a specialized flow
- the view is read-only or reporting-oriented
What it is:
- a custom label for the add button
How to configure it:
- enter a contextual action label such as
Add Task, Create Booking, Log Expense, or New Contact
- leave it empty to use the generic platform default
Why it matters:
- action wording can make the intent of the view much clearer
Use it when:
- the view has a strong business context and the default generic label would be vague
What it is:
- per-column label overrides for the view
How to configure it:
- provide a structured object where:
- keys are property system names or property IDs
- values are the column labels you want the view to display
Example:
{
"due_date": "Deadline",
"owner": "Responsible Person"
}
Why it matters:
- the same property can need different wording in different views
- this lets you adapt labels to the user's task without renaming the property globally
Runtime behavior:
- the view sanitizes and resolves these labels against the selected object type
- the custom names are also used in grouping and merging UI where relevant
Use it when:
- a property name is technically correct but not ideal in this specific work context
What it is:
- a role-based availability list for the view
How to configure it:
- select the roles that should have this view available
Why it matters:
- views are often role-specific workspaces
- not every role should see every operational surface, even when the underlying data type exists
Important distinction:
- this controls availability of the view itself
- it does not replace object-level create, edit, show, or delete permissions on the underlying type
Use it when:
- the same type needs different working views for different roles
- a specialized operational view should stay hidden from unrelated users
What it is:
- the message shown when the current query returns no results
How to configure it:
- enter a helpful empty-state message, such as:
No open tasks match the current filters.No files are stored in this folder yet.No bookings are scheduled for this period.
Why it matters:
- empty states are part of the user experience
- a good message helps users understand whether the view is functioning normally or whether they should widen filters or add data
Use it when:
- the view should speak in business language rather than generic system wording
What it is:
- the folders root used by the view
How to configure it:
- select a folders root when the view should expose folder navigation and folder-based organization for its objects
Why it matters:
- this gives the view folder awareness
- it enables folder browsing, counts, breadcrumb context, and folder assignment workflows against the chosen root
Use it when:
- the type needs document-like or hierarchy-like organization
- users should navigate records through folders in addition to filters
Avoid it when:
- folder semantics are not part of the working model
What it is:
- a structured settings object for advanced view configuration
How to configure it:
- in most cases, configure this through the
Layout builder
- only edit it manually if you understand the stored structure and have a strong reason to do so
Why it matters:
- this field stores viewer-specific layout configuration
- it is where Jetstack persists layout-builder output
What it typically contains:
layoutviewerLayouts- view-zone placement
- filter-zone placement
- custom buttons for layout zones
- zone settings
- advanced template configuration
Important practical rule:
- treat
settings as a managed configuration object rather than a casual free-form notes field
- the layout builder sanitizes and normalizes its contents before storage
Use it when:
- you need advanced layout control beyond the basic scalar view options
These options are what turn a view from a passive list into a contextual creation entry point.
What it is:
- values that must be applied when creating an object from this view
How to configure it:
- provide a structured object where:
- keys are property system names or property IDs
- values are the forced values to apply
Example:
{
"status": "Open",
"department": 14
}
Why it matters:
- these values define hard context for creation from this view
- they are stronger than defaults because the creation flow should treat them as fixed
Use it when:
- a record created from this view must always belong to a certain status, parent, queue, department, or other fixed context
Difference from defaults:
- forced values are for non-negotiable context
- default values are for suggested starting values
What it is:
- default values applied when a user starts creating an object from this view
How to configure it:
- provide an object where:
- keys are property system names or IDs
- values are the initial values to prefill
Example:
{
"priority": "Normal",
"country": "US"
}
Why it matters:
- defaults reduce repetitive input
- they still preserve user choice in cases where the field remains editable
Use it when:
- the view suggests a likely starting point but should not enforce it
What it is:
- fields that should be hidden in the creation flow started from this view
How to configure it:
- provide an array of property system names or IDs
Example:
[
"department",
"status"
]
Why it matters:
- a view can quietly apply context and avoid showing fields that users do not need to adjust in that flow
Use it together with:
adding_force_values when the hidden field should also be fixedadding_default_values when the hidden field should start with a value but remain context-driven
Design guidance:
- hide fields only when the context genuinely makes them unnecessary
- do not hide important business decisions that users still need to understand
The combination of query, relevant_queries, and persist_default_groups is one of the most important design areas of a view.
Use this pattern:
query defines the main starting perspectiverelevant_queries define alternative perspectives in the same workspacepersist_default_groups keeps structural grouping stable when that stability matters more than each query's own grouping defaults
This is a good fit for:
- work queues
- operational boards
- manager review screens
It is a poor fit for:
- unrelated report families that happen to target the same type
What it is:
- the configured list of actions available from the view
How to configure it:
- use the
Actions editor action on the view
- the field itself is stored as structured data and is not intended to be hand-edited in normal use
Why it matters:
- view actions are often the main operational controls of the screen
- they can turn a passive list into an action-oriented workspace
Important runtime behavior:
- if no custom action configuration exists, the platform falls back to default system export actions
- for custom-query views, some export variants are intentionally omitted
Types of view actions:
- export actions
- automation actions
- canvas actions
- divider entries for visual grouping
Each non-divider action can include the following practical settings.
What it controls:
- the user-facing label of the action
How to configure it:
- enter a clear verb-based label such as
Assign, Open Dashboard, Run Check, or Export Current Result
What it controls:
- what kind of target the action invokes
How to configure it:
- choose
automation when the action should run workflow logic
- choose
canvas when the action should open or render a canvas-based surface
What it controls:
- the automation target for automation-type actions
How to configure it:
- choose one automation in the actions editor
Use it when:
- the view should provide business operations such as assign, escalate, notify, enrich, or process
What it controls:
- the canvas target for canvas-type actions
How to configure it:
- choose one canvas in the actions editor
Use it when:
- the action should open a specialized interface, detail flow, or embedded experience
What it controls:
- the icon displayed with the action
How to configure it:
- choose a meaningful icon that distinguishes the action visually
What it controls:
- whether the action should be shown in the current runtime context
How to configure it:
- enter an expression that evaluates to a truthy or falsy result
- use the same expression approach described in Expressions
Why it matters:
- action visibility often depends on state, selection, permissions, or business conditions
Use it when:
- an action should only appear for certain object states or user situations
What it controls:
- whether the action runs through AJAX behavior
How to configure it:
- enable it for in-place interactions
- disable it when the action should behave more like a full navigation or full page transition
Divider entries do not execute anything. They exist only to visually separate action groups.
Use them when:
- a view has enough actions that grouping improves clarity
¶ Layout Builder And Per-Viewer Layout
The view resource includes a dedicated Layout builder action. This is where the more advanced settings payload is normally managed.
The layout builder stores viewer-specific layout configuration such as:
- which view components are visible
- which filter components are visible
- where those components are placed
- which viewers have dedicated layouts
- advanced template configuration
- custom zone buttons
The view's scalar fields tell Jetstack what the view is. The layout builder tells Jetstack how the chosen viewer should be composed.
That includes:
- title placement
- top button placement
- filter bar arrangement
- pagination visibility
- folders component placement
- tag component placement and tag editing availability
- calculations summary placement
- viewer selector availability
When a view should expose tags, the layout builder works with two separate tag-related features.
This is a view component that you place into one of the active view zones.
What it does:
- renders a tag-based search and filtering surface for the current view
- lets users narrow the current dataset by selected tags
- works as part of the view's filter and navigation layer
Use it when:
- users should filter the current view by tags
- tags should behave like a visible facet of the dataset
This is not the same thing as the Tag cloud component. It is a separate layout option controlled by the Inline tagging switch in the layout builder.
What it does:
- shows the current tags directly on listed objects
- lets users click existing tags on objects
- enables the per-object tag management UI where the viewer and permissions allow it
Use it when:
- users should see tag assignments directly in rows or cards
- the view should support lightweight tagging as part of day-to-day work
Practical rule:
- use
Tag cloud for filtering the dataset
- use
Inline tagging for displaying and maintaining tags on individual objects
These two features are often used together, but they are configured separately and one does not automatically enable the other.
Views can support runtime viewer switching, but this is not purely a matter of setting viewer.
For runtime switching to work well:
- the target viewer should have a layout configuration
- the layout should include the viewer selector component where appropriate
This matters because the platform determines active runtime viewer options from the configured layout state, not only from the default viewer field.
The layout builder also supports advanced template configuration.
Use it when:
- the standard slot-and-component layout is not expressive enough
- you need a more custom arrangement while still working inside the view system
Practical guidance:
- prefer the visual layout builder first
- use advanced template configuration only when the normal layout model is insufficient
These fields are mainly diagnostic or builder-supporting rather than day-to-day design controls.
What it is:
- the numeric internal identifier of the view
How to configure it:
- you do not configure it manually
Why it matters:
- it is useful for internal references, debugging, and synchronization diagnostics
What it is:
- a generated control snippet for rendering the view
How to configure it:
- you do not normally configure it manually
Why it matters:
- it represents the platform's render mask for the view control
- it is mainly useful as a system-level reference
What they are:
- system metadata about creation and last modification
How to configure them:
- they are managed by the platform
Why they matter:
- they help with auditability, troubleshooting, and implementation review
Configure:
viewer = table or kanban- one default
query
- several
relevant_queries
persist_default_groups = true when grouping should stay stable- clear
showCondition rules on important actions
Use it for:
- support queues
- approval worklists
- order processing
Configure:
show_add_button = true- contextual
add_button_text
adding_force_values for hard contextadding_default_values for suggested contextadding_hidden_values for fields users should not have to manage
Use it for:
- add task to project
- create issue in queue
- register expense in department
Configure:
viewer = calendarexplicit_start_property and explicit_end_property when date roles are ambiguous- a query suited to planning horizon and status scope
Use it for:
- bookings
- planned work
- deadlines and milestones
Configure:
- a suitable query
root with the intended folders root- useful custom column names
- creation defaults that respect folder context where needed
Use it for:
- document libraries
- structured case folders
- file-heavy operational surfaces
- Is this view for monitoring, triage, editing, planning, or reporting?
- Should one query define the screen, or should several relevant queries share it?
- Should users create new records from this view?
- Which values should be forced, suggested, or hidden during creation?
- Does the view need folder navigation?
- Should actions appear all the time, or only when expressions say they are relevant?
- Does the view need simple layout composition or a more advanced layout-builder setup?
- Design each view around one primary job to be done.
- Put durable data logic in queries and presentation logic in views.
- Use
relevant_queries for neighboring perspectives, not unrelated reports.
- Use
adding_force_values only for context that truly must be fixed.
- Keep
showCondition expressions readable and business-oriented.
- Treat
settings as managed layout configuration, not as a casual manual object.
- When several roles use the same type differently, prefer separate views with role-specific availability.