Groups are organizational containers for users. They let you model team or department context without turning that context directly into a permission role.
In Jetstack, a group can also carry homepage behavior and a shared dashboard definition. That makes a group more than a simple label on a user record. It can become the default working context for a set of users.
Groups help separate three concerns that should not be collapsed into one mechanism:
- who a user belongs with
- what a user is allowed to do
- where a user should land and what overview they should see first
Use groups to represent organizational structure, team ownership, or shared work context. Use roles and permissions to represent authorization. See Roles And Permissions.
This chapter describes the actual Group configuration surface exposed by the resource definition:
avatargroup_namedescriptionis_visibleis_activehomepage_moduledashboarddashboard_draft
The first six are ordinary configuration fields. The two dashboard fields are stored on the Group resource but are not intended to be edited as free-form data. They are managed through the Homepage dashboard editor UI.
A group does three different jobs in the platform:
- It gives users an organizational home.
- It can define a default homepage module for its members.
- It can define a shared dashboard layout used as the group homepage dashboard.
This means a group can shape the day-to-day experience of its members without replacing user-specific preferences or permission logic.
What it is:
- the image associated with the group
How to configure it:
- upload an image in the
avatar field
Why it matters:
- the avatar gives the group a recognizable identity in group listings and related UI surfaces
- it acts as the thumbnail-style visual representation of the group
When to use it:
- when the tenant uses several groups and benefits from quick visual recognition
- when groups represent teams, departments, or workspaces with a stable identity
Practical guidance:
- use a simple icon or emblem rather than a highly detailed image
- keep the asset visually consistent with the rest of the tenant branding
What it is:
- the primary name of the group
How to configure it:
- enter the group name in the
group_name field
- this field is required on both create and edit
Why it matters:
- this is the title field of the Group resource
- it is the main label shown when selecting, listing, or referencing the group
When to use it:
- always treat this as the stable organizational name of the group
Good examples:
FinanceOperationsCustomer SuccessRegional Support Team
Good practice:
- name groups after organizational meaning, not after temporary projects unless that is truly how the tenant is structured
What it is:
- a descriptive text field for the group
How to configure it:
- enter explanatory text in the
description field
Why it matters:
- it helps explain the role of the group to administrators and implementers
- it is searchable, so it can help with discovery in builder and management flows
When to use it:
- when the group name alone is not enough to explain who belongs there or what the group is for
Use it for:
- scope of responsibility
- intended audience
- onboarding notes for administrators
Avoid using it for:
- permission rules that should be defined formally elsewhere
- temporary operational notes that will quickly become outdated
What it is:
- a visibility flag on the group
How to configure it:
- enable or disable the
is_visible checkbox
Why it matters:
- this field expresses whether the group should be treated as visible from a governance and presentation perspective
- it is surfaced in group listings and synchronization payloads
Important implementation note:
- in the current codebase, this does not appear to act as a universal access-control switch
- treat it as a management and presentation flag, not as a substitute for permissions
When to use it:
- enable it for normal active groups that should be treated as ordinary visible organization units
- disable it when the group should remain in the data model but should not be treated as a normal front-facing organizational choice
Practical guidance:
- if hiding a group has business impact, document the intended behavior at tenant level because the field itself does not replace authorization design
What it is:
- the active-state flag of the group
How to configure it:
- enable or disable the
is_active checkbox
Why it matters:
- this records whether the group should be considered active from an organizational lifecycle perspective
- it helps distinguish live groups from archived or retired ones
When to use it:
- keep it enabled for groups that are currently in use
- disable it for retired groups that should stay referenced historically but are no longer part of normal operations
Important note:
- like
is_visible, this is not the same thing as permissions
- disabling a group does not by itself define the full authorization behavior of the users connected to it
Use this field as:
- an organizational lifecycle marker
- an administrative signal
Not as:
- the main enforcement mechanism for what users can access
What it is:
- the module to which users in this group should be redirected when homepage redirection is active
How to configure it:
- choose a Module in the
homepage_module field
Why it matters:
- this lets a group define a shared landing destination
- it is useful when one team should begin work in a specific module instead of the generic homepage dashboard
How it works:
- when a user has no user-specific homepage module override, the system can fall back to the
homepage_module configured on the user’s group
- if a valid group homepage module exists and the user does not prevent homepage redirection, the system redirects the user there from the homepage entry point
This creates an order of responsibility like this:
- user-specific homepage module, if defined
- otherwise the group
homepage_module
- otherwise the normal homepage behavior
When to use it:
- when all members of a team should start in the same operational module
- when the group’s work is centered around one primary workspace
Example:
- a support group can land directly in the support-ticket module
- a warehouse group can land directly in the inventory operations module
Practical guidance:
- only configure this when the landing module is truly shared across the group
- if group members have very different workflows, prefer user-specific homepage settings instead
What it is:
- the published shared dashboard layout for the group
How to configure it:
- do not configure this as a raw structured field
- manage it through the Homepage dashboard editor UI opened through the group dashboard editing action
Why it matters:
- this stores the group-level dashboard definition that can be used as the group homepage dashboard
- it determines which widgets are shown and with what configuration in the published group dashboard state
How it works:
- when editing a group dashboard, Jetstack stores a structured dashboard definition on the group
- the published state is saved into
dashboard
- that published state is what should be treated as the live group dashboard configuration
Important rule:
- although the field exists on the resource, it is not intended to be hand-authored in the generic object form
- the supported editing path is the Homepage dashboard editor UI
When to use it:
- when a whole team should share the same homepage dashboard composition
- when group-specific widgets or summaries are more useful than a generic homepage
What it is:
- the draft version of the group dashboard layout
How to configure it:
- do not configure this manually as raw structured data
- it is maintained automatically by the Homepage dashboard editor UI while changes are being edited before final save
Why it matters:
- it lets the platform keep an editable draft state separate from the published dashboard
- when a group dashboard is being edited, the editor can work with the draft first and then publish into
dashboard
How it works:
- during group dashboard editing, unsaved or draft-stage layout changes are stored in
dashboard_draft
- when the dashboard is finally saved as the published state, the platform writes the final structure into
dashboard and clears dashboard_draft
- when draft data exists, the editor prefers the draft during the editing flow
Important rule:
- this field is implementation data for the dashboard editor workflow
- document it as part of the Group model, but do not tell operators to edit it directly
The group resource exposes a dedicated action for editing the group dashboard. That is the supported configuration path for dashboard and dashboard_draft.
Use that UI when:
- you want to add or remove homepage widgets for the group
- you want to rearrange the group dashboard layout
- you want to update widget-specific configuration in the shared group dashboard
Think of the workflow this way:
dashboard_draft is the working copydashboard is the published copy
This distinction matters because it lets group dashboards be edited without immediately overwriting the currently published state.
Groups are also important because users reference them through their user_group field.
That means a group is not just a reporting label. It is part of the user model and can influence:
- organizational reporting
- user browsing and filtering
- homepage module fallback
- dashboard fallback behavior
The Group screen also includes a user-listing view of members in the group, which makes it a practical administrative hub for team management.
¶ How To Choose Between Groups And Roles
Use groups for:
- organizational belonging
- team structure
- shared landing context
- shared dashboard context
Use roles for:
- permissions
- access policy
- action rights
- system-level authorization design
If you find yourself wanting to use a group name to decide what a user is allowed to do, pause and move that logic into roles or permissions instead.
Suppose the tenant has a support department that should work from a common landing module and see a common operational dashboard.
Use this pattern:
- Create a Group called
Support.
- Upload an
avatar if visual identification is useful.
- Fill
description with the scope of the support team.
- Keep
is_visible and is_active enabled.
- Set
homepage_module to the support module.
- Open the group dashboard editor and compose the support dashboard there.
This gives the team:
- a common organizational identity
- a shared landing point
- a shared homepage dashboard
without turning the group itself into the permission system.
- Use groups for organizational structure, not for authorization logic.
- Keep
group_name stable and human-readable.
- Treat
homepage_module as a shared landing rule, not as a mandatory navigation hack for every user.
- Manage
dashboard and dashboard_draft only through the Homepage dashboard editor UI.
- Use
is_visible and is_active as governance and lifecycle signals, not as replacements for role design.
- Review group homepage behavior together with Users so user-level and group-level defaults do not conflict.