myjkkn-learner-profile
Pattern for fetching learner profiles from MyJKKN API with pagination support. Use when needing to retrieve learner photo URLs, DOB, or other profile data from MyJKKN. Handles the 200-record-per-page
SKILL.md.claude/skills/myjkkn-learner-profile/SKILL.md
GitHubMyJKKN Learner Profile Fetching
Pattern for retrieving learner profiles from MyJKKN API with proper institution filtering and pagination.
Key Constraints
- API Pagination: MyJKKN API returns max 200 records per page regardless of
limitparameter - Institution Filtering: Use
myjkkn_institution_idsarray from COEinstitutionstable - Matching Field: Match profiles by
register_numberonly (not roll_number) - Server-side filtering unreliable: Always filter by
institution_idclient-side after fetching
Environment Variables
const myjkknApiUrl = process.env.MYJKKN_API_URL // e.g., https://jkkn.ai
const myjkknApiKey = process.env.MYJKKN_API_KEY
Implementation Pattern
Step 1: Get myjkkn_institution_ids from COE Institution
const { data: institution } = await supabase
.from('institutions')
.select('myjkkn_institution_ids')
.eq('institution_code', institutionCode)
.single()
const myjkknInstIds: string[] = institution?.myjkkn_institution_ids || []
Step 2: Fetch Profiles with Pagination
Loop through each MyJKKN institution ID and paginate through all profiles:
let matchingProfile: any = null
for (const myjkknInstId of myjkknInstIds) {
if (matchingProfile) break // Stop if we found a match
let page = 1
const pageSize = 200
let hasMorePages = true
while (hasMorePages && !matchingProfile) {
const profileParams = new URLSearchParams()
profileParams.set('institution_id', myjkknInstId)
profileParams.set('limit', String(pageSize))
profileParams.set('page', String(page))
const profileResponse = await fetch(
`${myjkknApiUrl}/api-management/learners/profiles?${profileParams.toString()}`,
{
method: 'GET',
headers: {
'Authorization': `Bearer ${myjkknApiKey}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
cache: 'no-store',
}
)
if (profileResponse.ok) {
const profileData = await profileResponse.json()
const profiles = profileData.data || []
// Find matching profile by register_number only
matchingProfile = profiles.find((p: any) =>
p.register_number === targetRegisterNumber
)
// Check if there are more pages
hasMorePages = profiles.length === pageSize
page++
} else {
hasMorePages = false
}
}
}
Step 3: Extract Profile Data
Photo URL fields to check (in order of preference):
const photoUrl = matchingProfile?.student_photo_url
|| matchingProfile?.photo_url
|| matchingProfile?.profile_photo
|| matchingProfile?.image_url
|| null
const dob = matchingProfile?.date_of_birth || null
Complete Example
async function fetchLearnerProfile(
supabase: SupabaseClient,
institutionCode: string,
registerNumber: string
): Promise<{ photoUrl: string | null; dob: string | null }> {
const myjkknApiUrl = process.env.MYJKKN_API_URL
const myjkknApiKey = process.env.MYJKKN_API_KEY
if (!myjkknApiKey || !myjkknApiUrl) {
return { photoUrl: null, dob: null }
}
// Get myjkkn_institution_ids from COE institution
const { data: institution } = await supabase
.from('institutions')
.select('myjkkn_institution_ids')
.eq('institution_code', institutionCode)
.single()
const myjkknInstIds: string[] = institution?.myjkkn_institution_ids || []
if (myjkknInstIds.length === 0) {
return { photoUrl: null, dob: null }
}
let matchingProfile: any = null
for (const myjkknInstId of myjkknInstIds) {
if (matchingProfile) break
let page = 1
const pageSize = 200
let hasMorePages = true
while (hasMorePages && !matchingProfile) {
const profileParams = new URLSearchParams()
profileParams.set('institution_id', myjkknInstId)
profileParams.set('limit', String(pageSize))
profileParams.set('page', String(page))
try {
const profileResponse = await fetch(
`${myjkknApiUrl}/api-management/learners/profiles?${profileParams.toString()}`,
{
method: 'GET',
headers: {
'Authorization': `Bearer ${myjkknApiKey}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
cache: 'no-store',
}
)
if (profileResponse.ok) {
const profileData = await profileResponse.json()
const profiles = profileData.data || []
matchingProfile = profiles.find((p: any) =>
p.register_number === registerNumber
)
hasMorePages = profiles.length === pageSize
page++
} else {
hasMorePages = false
}
} catch (error) {
console.error('MyJKKN API error:', error)
hasMorePages = false
}
}
}
if (!matchingProfile) {
return { photoUrl: null, dob: null }
}
const photoUrl = matchingProfile.student_photo_url
|| matchingProfile.photo_url
|| matchingProfile.profile_photo
|| matchingProfile.image_url
|| null
const dob = matchingProfile.date_of_birth || null
return { photoUrl, dob }
}
Batch Fetching Pattern
For batch operations (multiple learners), fetch all profiles first, then match:
const allProfiles: any[] = []
for (const myjkknInstId of myjkknInstIds) {
let page = 1
const pageSize = 200
let hasMorePages = true
while (hasMorePages) {
const profileParams = new URLSearchParams()
profileParams.set('institution_id', myjkknInstId)
profileParams.set('limit', String(pageSize))
profileParams.set('page', String(page))
const response = await fetch(
`${myjkknApiUrl}/api-management/learners/profiles?${profileParams.toString()}`,
{
method: 'GET',
headers: {
'Authorization': `Bearer ${myjkknApiKey}`,
'Accept': 'application/json',
},
cache: 'no-store',
}
)
if (response.ok) {
const data = await response.json()
const profiles = data.data || []
allProfiles.push(...profiles)
hasMorePages = profiles.length === pageSize
page++
} else {
hasMorePages = false
}
}
}
// Create lookup map by register_number
const profileMap = new Map(
allProfiles.map(p => [p.register_number, p])
)
// Use map for O(1) lookup
const profile = profileMap.get(registerNumber)
API Endpoint Reference
- Endpoint:
GET /api-management/learners/profiles - Auth: Bearer token in Authorization header
- Query Params:
institution_id: MyJKKN institution UUID (required for filtering)limit: Page size (max 200 enforced by API)page: Page number (1-based)
- Response:
{ data: Profile[] }or direct array