Tags Management - Nudj Platform Documentation

Overview

The Nudj platform’s tagging system provides a powerful cross-cutting organizational tool for categorizing, filtering, and discovering content across all major entities. Tags enable better content organization, improved search capabilities, and enhanced user navigation throughout your community platform.

Key Features

Multi-Entity Support - Tags work across 8+ different content types
Icon Integration - 100,000+ icons via Iconify library
Advanced Search - Full-text search with MongoDB indexing
Bulk Operations - Mass tag assignment and removal
Analytics Integration - Tag-based filtering and reporting
Permission Control - Granular access management

Accessing Tags Configuration

Navigate to your tags management:

Go to Admin → Settings → Organisation
Click the Tags tab
View and manage all tags

Tags are organization-wide and can be applied across achievements, challenges, rewards, posts, communities, and more. Changes to tags affect all tagged content immediately.

Tag System Architecture

Supported Entities

Tags can be applied to:

Achievements

Categorize achievement types and difficulty levels

Challenges

Group challenges by theme, skill, or campaign

Rewards

Organize rewards by type, value, or availability

Posts

Categorize user-generated and admin content

Communities

Group communities by interest or department

Users

Tag users for segmentation and targeting

Events

Categorize events by type or audience

Resources

Organize learning materials and documents

Tag Properties

interface Tag {
  // Core Properties
  id: string;
  name: string;                  // Unique tag name
  displayName: string;           // User-friendly display name
  description?: string;          // Tag description
  
  // Visual Properties
  icon?: string;                 // Iconify icon identifier
  color?: string;                // Hex color code
  backgroundColor?: string;      // Background color
  
  // Organization
  category?: string;             // Tag category/group
  parentId?: string;            // Parent tag for hierarchy
  order?: number;               // Display order
  
  // Behavior
  isActive: boolean;            // Enable/disable tag
  isVisible: boolean;           // Show/hide from users
  isSystem: boolean;            // System-generated tag
  
  // Permissions
  permissions?: {
    view: string[];             // Who can see the tag
    assign: string[];           // Who can apply the tag
    edit: string[];            // Who can modify the tag
  };
  
  // Metadata
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
  usageCount: number;           // Number of tagged items
}

Creating and Managing Tags

Creating Tags

Define Tag Name

Enter a unique, descriptive tag name (lowercase, hyphens allowed)

Set Display Name

Add a user-friendly display name

Choose Icon

Select from 100,000+ Iconify icons

Select Color

Pick a color for visual distinction

Add Description

Provide context for when to use the tag

Configure Permissions

Set who can view and assign the tag

Tag Configuration Options

Basic Settings
Visual Settings
Permissions
Hierarchy

{
  name: "product-update",
  displayName: "Product Update",
  description: "Updates about product features and releases",
  category: "announcements",
  isActive: true,
  isVisible: true
}

Icon System

Using Iconify Icons

The platform integrates with Iconify, providing access to 100,000+ icons:

// Icon format: "prefix:icon-name"
// Example icons from different libraries:
[
  { icon: "mdi:home" },           // Material Design Icons
  { icon: "fa:user" },            // Font Awesome
  { icon: "heroicons:star" },     // Heroicons
  { icon: "carbon:data-1" },      // Carbon Icons
  { icon: "custom:brand-logo" }   // Custom uploaded icons
]

Icon Search and Selection

// Search available icons
const searchIcons = async (query: string) => {
  const results = await fetch(
    `https://api.iconify.design/search?query=${query}`
  );
  return results.json();
};

Tag Categories

Organizing Tags

Create categories to group related tags:

const tagCategories = {
  skills: {
    name: "Skills",
    tags: ["leadership", "communication", "technical"],
    color: "#10b981",
    icon: "mdi:school"
  },
  departments: {
    name: "Departments",
    tags: ["sales", "marketing", "engineering", "hr"],
    color: "#6366f1",
    icon: "mdi:office-building"
  },
  campaigns: {
    name: "Campaigns",
    tags: ["q1-2024", "product-launch", "holiday-special"],
    color: "#f59e0b",
    icon: "mdi:calendar-star"
  }
};

Category Management

Creating Categories

Define category name and description
Set default colors and icons
Configure category-wide permissions
Establish naming conventions

Category Rules

Tags can belong to one category
Categories can have sub-categories
Permissions can cascade from category
Categories affect search and filtering

Best Practices

Keep categories logical and intuitive
Limit to 5-10 main categories
Use consistent naming conventions
Document category purposes

Tag Assignment

Bulk Tagging

Apply tags to multiple items simultaneously:

Select Items

Choose items to tag from list view

Choose Tags

Select one or more tags to apply

Set Action

Add, remove, or replace existing tags

Confirm

Review changes and apply

Tag Rules and Automation

// Automatic tagging rules
const tagRules = [
  {
    trigger: "challenge_created",
    condition: {
      field: "type",
      operator: "equals",
      value: "quiz"
    },
    action: {
      addTags: ["quiz", "knowledge-check"]
    }
  },
  {
    trigger: "reward_added",
    condition: {
      field: "value",
      operator: "greater_than",
      value: 100
    },
    action: {
      addTags: ["high-value", "premium"]
    }
  }
];

Search and Filtering

Tag-Based Search

Implement powerful search with tags:

// Search with tag filters
const searchParams = {
  query: "team building",
  tags: {
    include: ["leadership", "collaboration"],
    exclude: ["archived"],
    matchType: "ANY" // ANY or ALL
  },
  entities: ["challenges", "posts"],
  limit: 20
};

Filter UI Components

The platform provides reusable filter components:

<TagFilter
  entities={["challenges", "rewards"]}
  selectedTags={selectedTags}
  onTagsChange={handleTagsChange}
  multiSelect={true}
  showCounts={true}
  groupByCategory={true}
/>

Analytics Integration

Tag-Based Analytics

Track content performance by tags:

Metric	Description	Use Case
Tag Usage	Frequency of tag application	Popular categories
Engagement by Tag	Views/interactions per tag	Content effectiveness
Tag Combinations	Common tag pairings	Content relationships
Tag Trends	Usage over time	Emerging topics
User Tag Preferences	Tags users interact with	Personalization

Achievement Event Filtering

Tags enable sophisticated achievement tracking:

{
  achievement: {
    name: "Sales Champion",
    eventFilter: {
      tags: ["sales", "q1-2024"],
      eventType: "challenge_completed",
      aggregation: "count",
      threshold: 5
    }
  }
}

Performance Optimization

Indexing Strategy

MongoDB indexes for optimal performance:

// Database indexes
db.tags.createIndex({ name: 1 }, { unique: true });
db.tags.createIndex({ "name": "text", "displayName": "text" });
db.tags.createIndex({ category: 1, order: 1 });
db.tags.createIndex({ isActive: 1, isVisible: 1 });

Caching

Tag data is cached for performance:

Tag List: 5-minute cache
Tag Counts: 1-minute cache
User Tag Preferences: Session cache
Filter Results: Request cache

Best Practices

Naming Conventions

Use lowercase with hyphens (e.g., “product-update”)

Limit Tag Count

Aim for 50-100 well-organized tags

Regular Cleanup

Archive unused tags periodically

Clear Descriptions

Help users understand tag purposes

Visual Distinction

Use colors and icons effectively

Monitor Usage

Track tag effectiveness with analytics

Migration and Import

Bulk Import

Import tags from CSV:

name,displayName,category,icon,color,description
leadership,Leadership,skills,mdi:account-tie,#10b981,Leadership and management skills
technical,Technical,skills,mdi:code-braces,#6366f1,Technical and programming skills
sales,Sales,departments,mdi:cash,#f59e0b,Sales department content

Export Configuration

curl -X GET https://your-subdomain.nudj.cx/api/v2/admin/tags/export \
  -H "x-api-token: $NUDJ_ADMIN_TOKEN" \
  -o tags-export.json

Troubleshooting

Tags not appearing in filters

Check isActive and isVisible settings
Verify user has permission to view tags
Clear cache and refresh
Check entity-specific tag configuration

Cannot assign tags

Verify assign permissions for user role
Check if tag limit exceeded
Ensure entity supports tagging
Check for tag restrictions

Icon not displaying

Verify Iconify icon name format
Check network connectivity to Iconify CDN
Try different icon set prefix
Clear browser cache

Search not finding tagged content

Rebuild search indexes
Check tag visibility settings
Verify search includes tag fields
Review tag matching logic (ANY vs ALL)

Bulk operations failing

Check selection limits (max 100 items)
Verify permissions for all selected items
Review error logs for specific failures
Try smaller batches

API Reference

Setup: First, export your Admin API token as an environment variable:

export NUDJ_ADMIN_TOKEN="your-admin-api-token"

curl -X GET https://your-subdomain.nudj.cx/api/v2/admin/tags \
  -H "x-api-token: $NUDJ_ADMIN_TOKEN"

Content Organization

Best practices for content structure

Search Configuration

Configure search and filtering

Analytics

Track tag-based metrics

API Documentation

Complete tags API reference

Getting Started

Dashboard & People

Core Engagement Features

Gamification System

Organization Settings

Advanced Features & Workflows

​Overview

Key Features

​Accessing Tags Configuration

​Tag System Architecture

​Supported Entities

Achievements

Challenges

Rewards

Posts

Communities

Users

Events

Resources

​Tag Properties

​Creating and Managing Tags

​Creating Tags

​Tag Configuration Options

​Icon System

​Using Iconify Icons

​Icon Search and Selection

​Tag Categories

​Organizing Tags

​Category Management

​Tag Assignment

​Bulk Tagging

​Tag Rules and Automation

​Search and Filtering

​Tag-Based Search

​Filter UI Components

​Analytics Integration

​Tag-Based Analytics

​Achievement Event Filtering

​Performance Optimization

​Indexing Strategy

​Caching

​Best Practices

Naming Conventions

Limit Tag Count

Regular Cleanup

Clear Descriptions

Visual Distinction

Monitor Usage

​Migration and Import

​Bulk Import

​Export Configuration

​Troubleshooting

​API Reference

​Related Resources

Content Organization

Search Configuration

Analytics

API Documentation

Overview

Accessing Tags Configuration

Tag System Architecture

Supported Entities

Tag Properties

Creating and Managing Tags

Creating Tags

Tag Configuration Options

Icon System

Using Iconify Icons

Icon Search and Selection

Tag Categories

Organizing Tags

Category Management

Tag Assignment

Bulk Tagging

Tag Rules and Automation

Search and Filtering

Tag-Based Search

Filter UI Components

Analytics Integration

Tag-Based Analytics

Achievement Event Filtering

Performance Optimization

Indexing Strategy

Caching

Best Practices

Migration and Import

Bulk Import

Export Configuration

Troubleshooting

API Reference

Related Resources