institution-filter
Complete guide for implementing institution-based data filtering in JKKN COE pages. This skill should be used when creating or updating pages that need to filter data by institution, implementing inst
SKILL.md.claude/skills/institution-filter/SKILL.md
GitHubInstitution Filter Skill
This skill provides patterns for implementing institution-based data filtering across the JKKN COE application.
Overview
The COE application is multi-tenant - users see only data belonging to their institution unless they are super_admin. This skill covers:
- Index Pages - Filtering data lists by institution
- Add/Edit Forms - Institution field visibility (show/hide based on context)
- Table Columns - Institution column visibility
- MyJKKN Integration - Direct UUID lookup using
myjkkn_institution_ids - Dependent Dropdowns - Cascading dropdowns that depend on institution selection
Core Hooks
1. useInstitutionFilter - For Index Pages & Forms
Location: hooks/use-institution-filter.ts
Provides filtering logic for data fetching and UI visibility control.
import { useInstitutionFilter } from '@/hooks/use-institution-filter'
const {
filter, // { institution_code?: string, institutions_id?: string }
isReady, // true when context is initialized
appendToUrl, // (url) => url with query params
getInstitutionIdForCreate, // () => institution_id for new records
mustSelectInstitution, // true when "All Institutions" is selected globally
shouldFilter, // true if filtering is active
institutionId // current institution id or null
} = useInstitutionFilter()
Key Properties:
| Property | Description |
|---|---|
filter |
Object with institution_code and institutions_id to pass to API |
isReady |
Boolean - wait for this before fetching data |
appendToUrl(url) |
Appends institution query params to URL |
getInstitutionIdForCreate() |
Returns institution ID for new records (auto-fills form) |
mustSelectInstitution |
true when "All Institutions" selected (show institution dropdown/column) |
shouldFilter |
true when filtering should be applied |
institutionId |
Current institution ID or null |
2. useInstitutionField - For Form Field Management
Location: hooks/use-institution-field.ts
Higher-level hook for managing institution dropdown in forms.
import { useInstitutionField } from '@/hooks/use-institution-field'
const {
shouldShowField, // true when dropdown should be visible
defaultInstitutionCode, // auto-fill value when field is hidden
defaultInstitutionId, // auto-fill ID value
availableInstitutions, // list of institutions for dropdown
isLoading // loading state
} = useInstitutionField()
3. useMyJKKNInstitutionFilter - For MyJKKN API Integration
Location: hooks/use-myjkkn-institution-filter.ts
NEW PATTERN: Uses myjkkn_institution_ids array directly from COE institutions table - no two-step lookup required!
Critical Constraints:
- COE institutions have
myjkkn_institution_ids: string[]field with MyJKKN UUIDs - MyJKKN API may ignore server-side
institution_idfiltering - always filter client-side - Deduplicate by CODE field (e.g.,
regulation_code,program_id), NOT byid - MyJKKN uses
program_idas the CODE field (like "BCA"), NOT as a UUID
import { useMyJKKNInstitutionFilter } from '@/hooks/use-myjkkn-institution-filter'
const {
fetchRegulations, // (myjkknInstitutionIds) => Promise<RegulationOption[]>
fetchLearnerProfiles, // (myjkknInstitutionIds, options) => Promise<LearnerProfileOption[]>
fetchPrograms, // (myjkknInstitutionIds, options) => Promise<ProgramOption[]>
fetchSemesters, // (myjkknInstitutionIds, options) => Promise<SemesterOption[]>
fetchBatches, // (myjkknInstitutionIds, options) => Promise<BatchOption[]>
fetchFilteredData // Generic function for any endpoint
} = useMyJKKNInstitutionFilter()
4. useMyJKKNPrograms - For Programs from MyJKKN
Location: hooks/myjkkn/use-myjkkn-data.ts
Declarative hook for fetching programs with auto-refresh on options change.
import { useMyJKKNPrograms } from '@/hooks/myjkkn/use-myjkkn-data'
const { data: programs, loading, error, refetch } = useMyJKKNPrograms({
is_active: true,
institution_code: institutionCode, // Optional - filter by institution
})
Database Schema: myjkkn_institution_ids
The COE institutions table has a myjkkn_institution_ids column:
-- institutions table
myjkkn_institution_ids TEXT[] -- Array of MyJKKN institution UUIDs
Example data:
| institution_code | counselling_code | myjkkn_institution_ids |
|---|---|---|
| CAS | CAS | ["a33138b6-4eea-4675-941f-1071bf88b127","b0b8a724-7c65-4f07-8047-2a38e8100ad5"] |
| CET | CET | ["uuid-1","uuid-2"] |
The array contains multiple UUIDs because MyJKKN has separate records for:
- Aided institution
- Self-financing (SF) institution
Both share the same counselling_code but have different id values.
UI Visibility Patterns
Pattern 1: Institution Field in Forms
Show institution dropdown when:
- "All Institutions" is selected globally (
mustSelectInstitution = true) - User can switch institutions (
!shouldFilter || !institutionId)
Hide when a specific institution is already selected (auto-fill from context).
{/* Show institution field when needed */}
{mustSelectInstitution || !shouldFilter || !institutionId ? (
<div className="space-y-2">
<Label>Institution <span className="text-red-500">*</span></Label>
<Select
value={formData.institutions_id}
onValueChange={(v) => setFormData({ ...formData, institutions_id: v })}
>
<SelectTrigger>
<SelectValue placeholder="Select institution" />
</SelectTrigger>
<SelectContent>
{institutions.map((inst) => (
<SelectItem key={inst.id} value={inst.id}>
{inst.institution_code} - {inst.institution_name}
</SelectItem>
))}
</SelectContent>
</Select>
</div>
) : null}
Pattern 2: Institution Column in Tables
Show Institution column only when "All Institutions" is selected globally.
<TableHeader>
<TableRow>
{/* Show Institution column only when "All Institutions" is selected */}
{mustSelectInstitution && (
<TableHead>Institution</TableHead>
)}
<TableHead>Code</TableHead>
<TableHead>Name</TableHead>
{/* ... other columns */}
</TableRow>
</TableHeader>
<TableBody>
{items.map((item) => (
<TableRow key={item.id}>
{mustSelectInstitution && (
<TableCell>
{institutions.find(i => i.id === item.institutions_id)?.institution_code || '-'}
</TableCell>
)}
<TableCell>{item.code}</TableCell>
<TableCell>{item.name}</TableCell>
</TableRow>
))}
</TableBody>
Pattern 3: Add Button Behavior
Add button should ALWAYS work - opens form directly without blocking.
- When
mustSelectInstitution = true: user selects institution in the form - When
mustSelectInstitution = false: institution auto-fills from context
<Button onClick={() => {
resetForm()
setSheetOpen(true)
}}>
<PlusCircle className="h-3 w-3 mr-1" />
Add
</Button>
MyJKKN Integration Pattern (NEW)
Pattern 4: Using myjkkn_institution_ids Directly
This is the recommended pattern. No two-step lookup required!
// State for institutions (must include myjkkn_institution_ids)
const [institutions, setInstitutions] = useState<Array<{
id: string
institution_code: string
institution_name: string
myjkkn_institution_ids: string[] | null // NEW: Direct UUIDs
}>>([])
// Hook for MyJKKN filtering
const { fetchPrograms } = useMyJKKNInstitutionFilter()
// Fetch programs when institution changes
const loadPrograms = async (institutionId: string) => {
setProgramsLoading(true)
setPrograms([])
// Get the institution with its myjkkn_institution_ids
const institution = institutions.find(i => i.id === institutionId)
const myjkknIds = institution?.myjkkn_institution_ids || []
if (myjkknIds.length === 0) {
console.warn('No MyJKKN institution IDs found')
setProgramsLoading(false)
return
}
// Use IDs directly - no lookup needed!
const progs = await fetchPrograms(myjkknIds)
setPrograms(progs)
setProgramsLoading(false)
}
// Effect: Refetch when institution changes
useEffect(() => {
if (formData.institutions_id) {
loadPrograms(formData.institutions_id)
} else {
setPrograms([])
}
}, [formData.institutions_id])
Pattern 5: Fetching Institutions with myjkkn_institution_ids
Always fetch myjkkn_institution_ids when loading institutions:
const fetchInstitutions = async () => {
try {
const res = await fetch('/api/master/institutions')
if (res.ok) {
const data = await res.json()
const mapped = Array.isArray(data)
? data.filter((i: any) => i?.institution_code).map((i: any) => ({
id: i.id,
institution_code: i.institution_code,
institution_name: i.institution_name || i.name,
myjkkn_institution_ids: i.myjkkn_institution_ids || [] // Include this!
}))
: []
setInstitutions(mapped)
}
} catch (e) {
console.error('Failed to load institutions:', e)
}
}
Pattern 6: Dependent Dropdowns (Programs, Regulations, Semesters)
From: course-management/course-mapping/add/page.tsx
'use client'
import { useState, useEffect } from 'react'
import { useMyJKKNInstitutionFilter } from '@/hooks/use-myjkkn-institution-filter'
export default function CourseMappingAddPage() {
const [institutions, setInstitutions] = useState<any[]>([])
const [programs, setPrograms] = useState<any[]>([])
const [regulations, setRegulations] = useState<any[]>([])
const [semesters, setSemesters] = useState<any[]>([])
const [programsLoading, setProgramsLoading] = useState(false)
const [regulationsLoading, setRegulationsLoading] = useState(false)
const [semestersLoading, setSemestersLoading] = useState(false)
const [selectedInstitution, setSelectedInstitution] = useState('')
const [selectedProgram, setSelectedProgram] = useState('')
const [selectedRegulation, setSelectedRegulation] = useState('')
// Hook for MyJKKN data fetching
const { fetchPrograms, fetchRegulations, fetchSemesters } = useMyJKKNInstitutionFilter()
// Fetch institutions on mount
useEffect(() => {
const loadInstitutions = async () => {
const res = await fetch('/api/master/institutions')
if (res.ok) {
const data = await res.json()
setInstitutions(data.map((i: any) => ({
id: i.id,
institution_code: i.institution_code,
name: i.name,
myjkkn_institution_ids: i.myjkkn_institution_ids || []
})))
}
}
loadInstitutions()
}, [])
// Fetch programs when institution changes
useEffect(() => {
if (!selectedInstitution) {
setPrograms([])
return
}
const loadPrograms = async () => {
setProgramsLoading(true)
const institution = institutions.find(i => i.institution_code === selectedInstitution)
const myjkknIds = institution?.myjkkn_institution_ids || []
if (myjkknIds.length === 0) {
setPrograms([])
setProgramsLoading(false)
return
}
const progs = await fetchPrograms(myjkknIds)
setPrograms(progs)
setProgramsLoading(false)
}
loadPrograms()
// Clear dependent selections
setSelectedProgram('')
setRegulations([])
setSemesters([])
}, [selectedInstitution, institutions, fetchPrograms])
// Fetch regulations when institution changes
useEffect(() => {
if (!selectedInstitution) {
setRegulations([])
return
}
const loadRegulations = async () => {
setRegulationsLoading(true)
const institution = institutions.find(i => i.institution_code === selectedInstitution)
const myjkknIds = institution?.myjkkn_institution_ids || []
if (myjkknIds.length === 0) {
setRegulations([])
setRegulationsLoading(false)
return
}
const regs = await fetchRegulations(myjkknIds)
setRegulations(regs)
setRegulationsLoading(false)
}
loadRegulations()
setSelectedRegulation('')
}, [selectedInstitution, institutions, fetchRegulations])
// Fetch semesters when program changes
useEffect(() => {
if (!selectedProgram || !selectedInstitution) {
setSemesters([])
return
}
const loadSemesters = async () => {
setSemestersLoading(true)
const institution = institutions.find(i => i.institution_code === selectedInstitution)
const myjkknIds = institution?.myjkkn_institution_ids || []
// Find the selected program to get its UUID
const program = programs.find(p => p.program_code === selectedProgram)
const programId = program?.id
const sems = await fetchSemesters(myjkknIds, { program_id: programId })
setSemesters(sems)
setSemestersLoading(false)
}
loadSemesters()
}, [selectedProgram, selectedInstitution, institutions, programs, fetchSemesters])
return (
<div className="space-y-4">
{/* Institution Select */}
<Select value={selectedInstitution} onValueChange={setSelectedInstitution}>
<SelectTrigger>
<SelectValue placeholder="Select Institution" />
</SelectTrigger>
<SelectContent>
{institutions.map((inst) => (
<SelectItem key={inst.institution_code} value={inst.institution_code}>
{inst.institution_code} - {inst.name}
</SelectItem>
))}
</SelectContent>
</Select>
{/* Program Select - depends on institution */}
<Select
value={selectedProgram}
onValueChange={setSelectedProgram}
disabled={!selectedInstitution || programsLoading}
>
<SelectTrigger className={!selectedInstitution ? 'bg-muted' : ''}>
<SelectValue placeholder={
!selectedInstitution
? "Select institution first"
: programsLoading
? "Loading programs..."
: programs.length === 0
? "No programs found"
: "Select program"
} />
</SelectTrigger>
<SelectContent>
{programs.map((prog) => (
<SelectItem key={prog.id} value={prog.program_code}>
{prog.program_code} - {prog.program_name}
</SelectItem>
))}
</SelectContent>
</Select>
{/* Regulation Select - depends on institution */}
<Select
value={selectedRegulation}
onValueChange={setSelectedRegulation}
disabled={!selectedInstitution || regulationsLoading}
>
<SelectTrigger className={!selectedInstitution ? 'bg-muted' : ''}>
<SelectValue placeholder={
!selectedInstitution
? "Select institution first"
: regulationsLoading
? "Loading regulations..."
: "Select regulation"
} />
</SelectTrigger>
<SelectContent>
{regulations.map((reg) => (
<SelectItem key={reg.id} value={reg.regulation_code}>
{reg.regulation_code} - {reg.regulation_name}
</SelectItem>
))}
</SelectContent>
</Select>
</div>
)
}
MyJKKN Field Naming Conventions
IMPORTANT: MyJKKN uses different field names than you might expect:
| Field | Description | Example Value |
|---|---|---|
id |
UUID (actual unique identifier) | a33138b6-4eea-4675-941f-1071bf88b127 |
program_id |
Program CODE (NOT a UUID!) | BCA, MCA, MBA |
regulation_code |
Regulation CODE | REG2020, REG2023 |
institution_id |
Institution UUID | a33138b6-4eea-4675-941f-1071bf88b127 |
Deduplication Rules:
- Programs: Deduplicate by
program_id(the CODE field) - Regulations: Deduplicate by
regulation_code - Semesters: Deduplicate by
id(actual UUID) - Batches: Deduplicate by
id(actual UUID) - Learners: Deduplicate by
id(actual UUID)
Complete Page Pattern
'use client'
import { useState, useEffect, useCallback } from 'react'
import { useInstitutionFilter } from '@/hooks/use-institution-filter'
import { useMyJKKNInstitutionFilter } from '@/hooks/use-myjkkn-institution-filter'
export default function EntityPage() {
// Institution filter hook
const {
filter,
isReady,
appendToUrl,
getInstitutionIdForCreate,
mustSelectInstitution,
shouldFilter,
institutionId
} = useInstitutionFilter()
// MyJKKN integration
const { fetchRegulations, fetchPrograms } = useMyJKKNInstitutionFilter()
// State
const [items, setItems] = useState([])
const [loading, setLoading] = useState(true)
const [sheetOpen, setSheetOpen] = useState(false)
const [editing, setEditing] = useState(null)
const [institutions, setInstitutions] = useState<Array<{
id: string
institution_code: string
institution_name: string
myjkkn_institution_ids: string[] | null
}>>([])
const [regulations, setRegulations] = useState([])
const [regulationsLoading, setRegulationsLoading] = useState(false)
// Form state
const [formData, setFormData] = useState({
institutions_id: '',
code: '',
name: '',
regulation_id: ''
})
const [errors, setErrors] = useState<Record<string, string>>({})
// Fetch data with institution filter
const fetchData = async () => {
try {
setLoading(true)
const url = appendToUrl('/api/entity')
const response = await fetch(url)
if (response.ok) {
const data = await response.json()
setItems(data)
}
} finally {
setLoading(false)
}
}
// Fetch institutions (include myjkkn_institution_ids)
const fetchInstitutions = async () => {
try {
const res = await fetch('/api/master/institutions')
if (res.ok) {
const data = await res.json()
const mapped = Array.isArray(data)
? data.filter((i: any) => i?.institution_code).map((i: any) => ({
id: i.id,
institution_code: i.institution_code,
institution_name: i.institution_name || i.name,
myjkkn_institution_ids: i.myjkkn_institution_ids || []
}))
: []
setInstitutions(mapped)
}
} catch (e) {
console.error('Failed to load institutions:', e)
}
}
// Fetch regulations from MyJKKN using myjkkn_institution_ids
const loadRegulations = useCallback(async (instId?: string) => {
try {
setRegulationsLoading(true)
setRegulations([])
if (!instId) return
const institution = institutions.find(i => i.id === instId)
const myjkknIds = institution?.myjkkn_institution_ids || []
if (myjkknIds.length === 0) {
console.warn('No MyJKKN institution IDs for:', institution?.institution_code)
return
}
// Use IDs directly - no lookup needed!
const regs = await fetchRegulations(myjkknIds)
setRegulations(regs.map(r => ({
id: r.id,
regulation_code: r.regulation_code,
regulation_name: r.regulation_name || r.regulation_code
})))
} finally {
setRegulationsLoading(false)
}
}, [institutions, fetchRegulations])
// Load data when institution filter is ready
useEffect(() => {
if (isReady) {
fetchData()
fetchInstitutions()
}
}, [isReady, filter])
// Fetch regulations when form institution changes
useEffect(() => {
if (formData.institutions_id) {
loadRegulations(formData.institutions_id)
} else {
setRegulations([])
}
}, [formData.institutions_id, loadRegulations])
// Reset form with auto-filled institution
const resetForm = () => {
const autoInstitutionId = getInstitutionIdForCreate() || ''
setFormData({
institutions_id: autoInstitutionId,
code: '',
name: '',
regulation_id: ''
})
setErrors({})
setEditing(null)
}
// Handle edit - populate form with existing data
const handleEdit = (item) => {
setEditing(item)
setFormData({
institutions_id: item.institutions_id,
code: item.code,
name: item.name,
regulation_id: item.regulation_id || ''
})
setSheetOpen(true)
}
return (
<>
{/* Data Table */}
<Table>
<TableHeader>
<TableRow>
{mustSelectInstitution && <TableHead>Institution</TableHead>}
<TableHead>Code</TableHead>
<TableHead>Name</TableHead>
<TableHead>Actions</TableHead>
</TableRow>
</TableHeader>
<TableBody>
{items.map((item) => (
<TableRow key={item.id}>
{mustSelectInstitution && (
<TableCell>
{institutions.find(i => i.id === item.institutions_id)?.institution_code || '-'}
</TableCell>
)}
<TableCell>{item.code}</TableCell>
<TableCell>{item.name}</TableCell>
<TableCell>
<Button onClick={() => handleEdit(item)}>Edit</Button>
</TableCell>
</TableRow>
))}
</TableBody>
</Table>
{/* Add Button - Always works */}
<Button onClick={() => { resetForm(); setSheetOpen(true) }}>Add</Button>
{/* Form Sheet */}
<Sheet open={sheetOpen} onOpenChange={(o) => { if (!o) resetForm(); setSheetOpen(o) }}>
<SheetContent>
<form>
{/* Institution field - show only when needed */}
{mustSelectInstitution || !shouldFilter || !institutionId ? (
<div className="space-y-2">
<Label>Institution <span className="text-red-500">*</span></Label>
<Select
value={formData.institutions_id}
onValueChange={(v) => setFormData({
...formData,
institutions_id: v,
regulation_id: '' // Clear dependent field
})}
>
<SelectTrigger>
<SelectValue placeholder="Select institution" />
</SelectTrigger>
<SelectContent>
{institutions.map((inst) => (
<SelectItem key={inst.id} value={inst.id}>
{inst.institution_code} - {inst.institution_name}
</SelectItem>
))}
</SelectContent>
</Select>
</div>
) : null}
{/* Dependent regulation dropdown */}
<div className="space-y-2">
<Label>Regulation</Label>
<Select
value={formData.regulation_id}
onValueChange={(v) => setFormData({ ...formData, regulation_id: v })}
disabled={!formData.institutions_id || regulationsLoading}
>
<SelectTrigger className={!formData.institutions_id ? 'bg-muted' : ''}>
<SelectValue placeholder={
!formData.institutions_id
? "Select institution first"
: regulationsLoading
? "Loading..."
: "Select regulation"
} />
</SelectTrigger>
<SelectContent>
{regulations.map((reg) => (
<SelectItem key={reg.id} value={reg.id}>
{reg.regulation_code}
</SelectItem>
))}
</SelectContent>
</Select>
</div>
{/* Other form fields */}
<Input
value={formData.code}
onChange={(e) => setFormData({ ...formData, code: e.target.value })}
/>
</form>
</SheetContent>
</Sheet>
</>
)
}
Validation Pattern
const validate = () => {
const e: Record<string, string> = {}
// Institution is required
if (!formData.institutions_id) {
e.institutions_id = 'Institution is required'
}
// Other validations...
if (!formData.code.trim()) {
e.code = 'Code is required'
}
setErrors(e)
return Object.keys(e).length === 0
}
Colspan Adjustment for Tables
When Institution column visibility changes, adjust colspan for empty/loading states:
<TableRow>
<TableCell
colSpan={mustSelectInstitution ? 8 : 7}
className="text-center"
>
{loading ? 'Loading...' : 'No data'}
</TableCell>
</TableRow>
Common Mistakes to Avoid
- Fetching before filter is ready - Always check
isReadybefore fetching - Not using
appendToUrl- Use this to add institution params to API calls - Blocking Add button - Add button should always work; institution selected in form
- Forgetting to reset form - Use
getInstitutionIdForCreate()inresetForm() - Hardcoding column counts - Adjust colspan based on
mustSelectInstitution - MyJKKN: Trusting server-side filtering - Always filter client-side by
institution_id - MyJKKN: Deduplicating by
id- Deduplicate by code field (e.g.,regulation_code,program_id) - Not clearing dependent fields - When institution changes, clear dependent dropdowns
- Not showing loading state - Show "Loading..." in dependent dropdowns while fetching
- Not including
myjkkn_institution_ids- Always fetch this field with institutions - Using
counselling_codelookup - Usemyjkkn_institution_idsdirectly (no lookup needed!)
Summary: When to Use Which Hook
| Use Case | Hook |
|---|---|
| Filter index page data | useInstitutionFilter + appendToUrl() |
| Show/hide institution field in forms | useInstitutionFilter + mustSelectInstitution |
| Auto-fill institution for new records | useInstitutionFilter + getInstitutionIdForCreate() |
| Fetch MyJKKN data by institution | useMyJKKNInstitutionFilter + myjkkn_institution_ids |
| Fetch programs (declarative) | useMyJKKNPrograms + client-side filter |
| Generic MyJKKN data with filtering | useMyJKKNInstitutionFilter + specific fetch method |
Migration from Old Pattern (counselling_code)
If you have code using the old two-step counselling_code lookup pattern:
OLD (deprecated):
const { fetchRegulations } = useMyJKKNInstitutionFilter()
// Old: Pass counselling_code, hook does two-step lookup
const institution = institutions.find(i => i.id === institutionId)
const regs = await fetchRegulations(institution?.counselling_code)
NEW (recommended):
const { fetchRegulations } = useMyJKKNInstitutionFilter()
// New: Pass myjkkn_institution_ids directly, no lookup needed!
const institution = institutions.find(i => i.id === institutionId)
const myjkknIds = institution?.myjkkn_institution_ids || []
const regs = await fetchRegulations(myjkknIds)
The new pattern is simpler and more efficient - it uses the pre-populated myjkkn_institution_ids array directly instead of making an extra API call to look up institution IDs by counselling_code.