Links

Overview

The Links feature provides a streamlined way to manage and organize quick access links to important websites and resources. It supports link grouping, custom ordering, audience-based visibility, and both user and admin interfaces for accessing and managing links.

Key Features

Link Organization

• Link Groups: Organize links into logical groups
• Custom Ordering: Control the order of links within groups
• Default Group: Ungrouped links appear in "General" group
• Group Sorting: "General" group always appears first, others alphabetically

Link Properties

• Title and URL: Basic link information
• Target Control: Open in new tab (_blank) or same window
• Thumbnail Support: Optional thumbnail images for visual identification
• Group Assignment: Organize links into named groups

Access Control

• Audience Filtering: Show links only to specific audience members
• Admin Management: Admin-only link creation and editing
• Public Access: Links without audiences visible to all
• Permission Checks: Manage links requires admin privileges

User Interface

• Clean Layout: Simple, focused interface for link access
• Card-Based Design: Visual cards for each link
• Grouped Display: Links organized by assigned groups
• Quick Actions: Edit and delete options for admins

Database Models

Link Model

model Link {
  id        String     @id @default(cuid())
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt
  tenantId  String
  tenant    Tenant     @relation(fields: [tenantId], references: [id])
  userId    String
  user      User       @relation(fields: [userId], references: [id])
  title     String
  url       String
  target    String     @default("_blank")
  thumbnail String?
  group     String?
  order     Int        @default(0)
  audience  Audience[]
}

Routes

User Routes

• /app/{tenant}/links - View all accessible links

Features:

• Clean, focused interface
• Grouped link display
• No search or filters (simplified view)
• Direct link access

Admin Management

Link management is embedded in the user view with conditional UI:

• Admin users see edit and add buttons
• Regular users see only their accessible links
• Create, edit, and delete operations require admin permissions

Link Management

Creating a Link

await createLink({
  tenantId,
  userId,
  title,
  url,
  target: target || "_blank",
  thumbnail: thumbnail || undefined,
  group: group || undefined,
  audienceIds,
});

Required fields:

• title: Link display name
• url: Link destination URL

Optional fields:

• target: _blank (new tab) or _self (same window), defaults to _blank
• thumbnail: Image URL for visual identification
• group: Group name for organization
• audienceIds: Restrict visibility to specific audiences

Updating a Link

await updateLink({
  item,
  title,
  url,
  target,
  thumbnail,
  group,
  audienceIds,
});

All fields can be updated except:

• id: Immutable identifier
• tenantId: Tenant isolation
• createdAt: Creation timestamp

Deleting a Link

await deleteLink({ item });

Deletion is permanent and cannot be undone.

Link Grouping

Group Structure

Links are organized into groups for better organization:

const groupedLinks = links.reduce((acc, link) => {
  const groupName = link.group || "General";
  if (!acc[groupName]) {
    acc[groupName] = [];
  }
  acc[groupName].push(link);
  return acc;
}, {} as Record<string, typeof links>);

Group Sorting

Groups are automatically sorted:

1. "General" group always appears first
2. Other groups sorted alphabetically
3. Links within groups sorted by order field

const sortedGroups = Object.keys(groupedLinks).sort((a, b) => {
  if (a === "General") return -1;
  if (b === "General") return 1;
  return a.localeCompare(b);
});

Access Control

Permission Requirements

• View Links: All authenticated users with links feature access
• Manage Links: Admin users only (getIsSuperUserOrAdmin)
• Create Links: Admin only
• Edit Links: Admin only
• Delete Links: Admin only

Audience Filtering

Links are filtered based on user's audience membership:

const items = await getLinks({
  tenantId,
  audienceUserId: await shouldFilterByAudienceUserId("reports", { request, params }),
});

Visibility rules:

• No audience = visible to all
• Has audience = visible only to audience members
• Admin users see all links for management

User Interface

Link Card Component

Each link is displayed as a card:

• Link title
• Click to open URL
• Edit button (admin only)
• Target configured as _blank or _self

Layout

• Header with title and description
• Grouped link sections
• Add button in footer (admin only)
• Edit dialog for link modifications

Empty State

When no links exist:

<EmptyStateSimple>No links</EmptyStateSimple>

Best Practices

1. Descriptive Titles: Use clear, concise link titles
2. URL Validation: Ensure URLs are complete and valid before saving
3. Grouping Strategy: Create logical groups based on link purpose or department
4. Ordering: Set order values to control link sequence within groups
5. Thumbnails: Add thumbnails for frequently used links
6. Audience Assignment: Use audiences to segment departmental or role-specific links
7. Target Setting: Use _blank for external links, _self for internal navigation

Common Operations

Create a Link

1. Click "+" button (visible to admins only)
2. Enter link details:
   • Title (required)
   • URL (required)
   • Target (_blank or _self)
   • Thumbnail URL (optional)
   • Group name (optional)
3. Assign audiences (optional)
4. Click "Save"

Edit a Link

1. Click edit icon on link card (admin only)
2. Update link details
3. Modify audience assignments
4. Click "Save"

Delete a Link

1. Click delete option in edit dialog
2. Confirm deletion
3. Link permanently removed

Organize Links by Group

1. When creating/editing a link, enter group name
2. Links with same group name appear together
3. "General" group for ungrouped links
4. Groups auto-sort alphabetically (except "General" first)

Set Link Order

1. Edit link
2. Set order value (higher numbers appear later)
3. Links within same group sort by order
4. Default order is 0

Integration Points

• Audiences: Audience-based link visibility
• Users: Track link creators and editors
• Tenants: Multi-tenant isolation for links
• Feature Access: Requires links feature to be enabled for tenant
• Admin Permissions: Admin controls for link management

Example Use Cases

1. Department Links: Create "HR" group with links to HR systems
2. Quick Access: "General" group for commonly used tools
3. External Resources: Links to vendor portals, training sites
4. Internal Tools: Links to internal dashboards, wikis
5. Role-Based Access: IT team links visible only to IT audience