Milestone: M3 — Issuing Functionality | SOW Reference: FR1 (cross-cutting overview) | Requirement Clarity: ✅ Clear | Dev Status: 🟢 Prototyped in POC Moved from docs/requirements/tasks/POC/02-employee-credential-management-system.md. Cross-cutting overview spanning M3-00 itself plus M3-01, M3-02, M3-03 and M3-10. Its own "Pending Phases" note (CSV upload, VNF batch issuance) is now out of date — the codebase audit run on 2026-08-12 confirms both have since been built (see M3-03).

M3-00 Employee Credential Management System - REC MVP¶

✅ COMPLETION STATUS: IMPLEMENTED AND OPERATIONAL¶

Implementation Summary (Completed: January 2026)¶

The Employee Credential Management System has been successfully implemented with all core features operational and production-ready:

✅ COMPLETED PHASES: - Phase 1: Employee Management System - Complete CRUD operations, search, pagination, bulk operations - Phase 2: Manual Credential Creation - VNF-compliant credential issuance with template management - Phase 5: Credential Management Dashboard - Analytics, tracking, and management interface

📋 PENDING PHASES (Next Development Cycle): - Phase 3: CSV Employee Upload - Bulk employee import functionality - Phase 4: VNF Batch Credential Issuance - Integration with @velocitycareerlabs/data-loader

🔗 IMPLEMENTED COMPONENTS: - Employee Entity - VNF EmploymentPastV1.1 compliant - Employee Service - Complete business logic - Employee Controller - 15+ REST endpoints - Credential Template Service - Template management - Manual Credential Service - Individual issuance - Employee Management UI - Complete frontend interface - Credentials Dashboard - Management interface

🎯 PRODUCTION READY FEATURES: - Employee CRUD with unique ID generation (EMP001234567 format) - VNF-compliant credential templates with Handlebars processing - Manual credential issuance workflow - Comprehensive search, filtering, and pagination - Multi-tenant data segregation - Status tracking and analytics - Mock VNF SDK integration ready for production

🎯 Official VNF & REC Requirements¶

PRIMARY REFERENCES:¶

VNF SDK: vnf-wallet-sdk-nodejs-main/
VNF Batch Issuing Documentation: Official VNF data-loader implementation
REC Platform Requirements: REC Verifiable Credentialing Platform High-level Requirements v3.0
Official Credential Types: VNF Certified Credential Types

Key Reference Files: - Data Validation: packages/sample-app/src/Constants.ts:58 - Employee data structure patterns - Batch Processing: packages/sample-app/src/screens/MeinScreen.tsx:140 - Batch credential generation workflow - Data Conversion: packages/sample-server/src/utils/Converter.ts:154 - Data transformation patterns

Overview¶

REC MVP implementation for UK Employment sector focusing on Past Employment Credentials with complete employee-to-credential workflow:

Supported Credential Types (Official VNF Certified)¶

Primary: EmploymentPastV1.1 (Recommended) - Past employment credentials
Secondary: EmploymentCurrentV1.1 (Recommended) - Current employment credentials
Identity Verification: EmailV1.0, PhoneV1.0, DriversLicenseV1.0 (for candidate identification)

Core Workflow¶

Employee Management: Create and manage employee records with unique Employee IDs
Manual Credential Creation: Individual past employment credential issuance via web form
Batch Credential Issuance: CSV-based bulk credential issuance using VNF data-loader
Credential Management Dashboard: Track, manage, and verify all issued credentials
Candidate Experience: Email/QR code delivery with configurable landing pages

Phase 1: Employee Management System¶

Backend Tasks¶

Employee Entity & Database¶

Task: Create employee data model aligned with VNF EmploymentPastV1.1 schema
Create employee.entity.ts
Core Fields (VNF EmploymentPastV1.1 compliant):
- employeeId (unique identifier for VNF batch processing)
- firstName, lastName (Person name v1.1 sub-type)
- email (primary identifier for EmailV1.0 credential)
- phone (optional identifier for PhoneV1.0 credential)
- jobTitle, department, workLocation (Organization v1.1 sub-type)
- startDate, endDate (employment period)
- employmentStatus (active, terminated, resigned, etc.)
Extended Fields (REC specific):
- supervisorName, supervisorEmail, supervisorTitle
- salaryAmount, currency, salaryPeriod
- performanceRating, skills, responsibilities
- reasonForLeaving, eligibleForRehire, additionalNotes
Audit Fields: createdAt, updatedAt, createdBy, organizationId
Add unique constraints and indexes for performance

Employee Service¶

Task: Implement employee CRUD operations
Create employee.service.ts
Implement create, read, update, delete operations
Add employee search and filtering
Generate unique Employee IDs
Validate employee data integrity

Employee Controller¶

Task: Create employee management endpoints
Create employee.controller.ts
Implement REST endpoints for employee CRUD
Add bulk employee operations
Include employee search and pagination

Employee DTOs¶

Task: Create data transfer objects
Create employee.dto.ts
Define CreateEmployeeDto, UpdateEmployeeDto, EmployeeResponseDto
Add validation rules for all fields
Include search and filter DTOs

Frontend Tasks¶

Employee Management Components¶

Task: Create employee management interface
Create EmployeeList.tsx
Create EmployeeForm.tsx
Create EmployeeDetails.tsx
Implement search, filter, and pagination
Add employee creation and editing forms

Add routing here app/frontend/src/components/Header.tsx:32-34

  ],
  ORG_ADMIN: [
    { label: 'Dashboard', href: '/admin/dashboard' },

Employee Pages¶

Task: Create employee management pages
Create employees/index.tsx
Create employees/new.tsx
Create employees/[id]/edit.tsx
Create employees/[id]/index.tsx

Phase 2: Manual Credential Creation¶

Backend Tasks¶

VNF Credential Template Management¶

Task: Implement VNF-compliant credential template system
Create credential-template.entity.ts
Create credential-template.service.ts
Template Types:
- EmploymentPastV1.1 - Past employment credential template
- EmploymentCurrentV1.1 - Current employment credential template
Support Handlebars template format as per VNF batch issuing documentation
Template variables: {{{email}}}, {{{firstName}}}, {{{lastName}}}, {{{jobTitle}}}, etc.
Store template validation rules and required fields

Manual Credential Service (REC Web Form)¶

Task: Implement individual past employment credential creation
Create manual-credential.service.ts
VNF Integration: Direct integration with Velocity Credential Agent
Support employee lookup by Employee ID with auto-fill
Credential Generation: Create EmploymentPastV1.1 credentials
Identity Verification: Support EmailV1.0 (primary), PhoneV1.0, DriversLicenseV1.0
Delivery: Generate QR codes, deep links, and configurable email notifications
REC Compliance: Configurable landing pages and email templates per organization

Frontend Tasks¶

Manual Credential Form¶

Task: Implement the manual credential creation form (based on UI design)
Create ManualCredentialForm.tsx
Include all fields from UI design:
- Candidate Information (First Name, Last Name, Email, Phone, Employee ID)
- Employment Details (Job Title, Department, Start Date, End Date, Employment Status, Work Location)
- Salary Information (Amount, Currency, Period)
- Performance & Skills (Rating, Skills & Competencies, Key Responsibilities)
- Supervisor Information (Name, Title, Email)
- Additional Information (Reason for Leaving, Eligible for Rehire, Notes)
Add Employee ID lookup and auto-fill functionality
Implement form validation and submission

Phase 3: CSV Employee Upload¶

Backend Tasks¶

CSV Upload Controller¶

Task: Create employee CSV upload endpoint
Create employee-upload.controller.ts
Implement POST /api/v1/issuer/employees/upload endpoint
Add Multer configuration for CSV file handling
Implement file size and type validation (max 10MB, .csv only)

CSV Processing Service¶

Task: Implement CSV parsing and validation
Create employee-csv-processor.service.ts
Add CSV parsing using csv-parser library
Validate all employee fields as per entity definition
Generate Employee IDs for new records
Handle duplicate detection and updates
Support batch employee creation

Frontend Tasks¶

Employee Upload Interface¶

Task: Create CSV upload component for employees
Create EmployeeUpload.tsx
Implement drag-and-drop functionality using react-dropzone
Add CSV template download
Show upload progress and validation results
Display preview of employee data before processing

Phase 4: Batch Credential Issuance (VNF Integration)¶

Backend Tasks¶

VNF Batch Issuing Integration (Official Data-Loader)¶

Task: Implement official VNF batch issuing workflow using @velocitycareerlabs/data-loader
Create vnf-batch-issuer.service.ts
Core Integration: npx @velocitycareerlabs/data-loader batchissuing [options]
Required Parameters:
- -d [DID] - Issuing organization DID
- -e [URL] - Credential Agent server URL
- -a [AUTH_TOKEN] - Bearer token for Credential Agent
- -c [CSV_PATH] - CSV file with employee data (email as first column)
- -o [OFFER_TEMPLATE_PATH] - Handlebars template path
- -t [URL] - Terms and conditions URL
CSV Format: Email (first column), Employee ID, firstName, lastName, jobTitle, etc.
Template Processing: Handlebars variables {{{email}}}, {{{employeeId}}}, {{{firstName}}}, etc.
Output: QR codes (qrcode-[EMAIL].png), deep links, and CSV output with -x flag
Identity Types: Support EmailV1.0 (default), PhoneV1.0, DriversLicenseV1.0 via -y flag
Batch Tracking: Monitor processing status and handle errors

Batch Credential Controller¶

Task: Create batch credential endpoints
Create batch-credential.controller.ts
Implement batch credential creation from employee list
Support CSV upload for batch issuance
Add progress tracking and status updates
Include error handling and reporting

Credential Tracking¶

Task: Implement credential issuance tracking
Create credential-issuance.entity.ts
Track credential status: PENDING, ISSUED, CLAIMED, EXPIRED
Store QR code paths and deep links
Link credentials to employees via Employee ID
Add batch processing metadata

Frontend Tasks¶

Batch Credential Interface¶

Task: Create batch credential issuance interface
Create BatchCredentialForm.tsx
Support employee selection (individual or bulk)
CSV upload for batch processing
Template selection and customization
Progress tracking and status updates

Phase 5: Credential Management Dashboard¶

Backend Tasks¶

Credential Management Service¶

Task: Implement credential management operations
Create credential-management.service.ts
Support credential search and filtering
Implement status tracking and updates
Add credential analytics and reporting
Support credential revocation and expiry

Frontend Tasks¶

Credential Management Dashboard¶

Task: Implement the credential management dashboard (based on UI design)
Create CredentialDashboard.tsx
Display credential statistics (Total Issued, Claimed, Pending, Expired)
Implement credential list with search and filters
Add bulk actions for credential management
Include export functionality (CSV)
Support credential status updates

Credential List Component¶

Task: Create detailed credential list
Create CredentialList.tsx
Display credentials with candidate info, job title, employment period, issue date, status
Add sorting and pagination
Include individual credential actions
Support bulk selection and operations

API Endpoints¶

Employee Management¶

GET /api/v1/issuer/employees - List employees with pagination and filters
POST /api/v1/issuer/employees - Create new employee
GET /api/v1/issuer/employees/{employeeId} - Get employee details
PUT /api/v1/issuer/employees/{employeeId} - Update employee
DELETE /api/v1/issuer/employees/{employeeId} - Delete employee
POST /api/v1/issuer/employees/upload - Upload employee CSV
GET /api/v1/issuer/employees/search - Search employees

Credential Management¶

POST /api/v1/issuer/credentials/manual - Create individual credential
POST /api/v1/issuer/credentials/batch - Create batch credentials
GET /api/v1/issuer/credentials - List credentials with filters
GET /api/v1/issuer/credentials/{credentialId} - Get credential details
PUT /api/v1/issuer/credentials/{credentialId}/status - Update credential status
DELETE /api/v1/issuer/credentials/{credentialId} - Revoke credential
GET /api/v1/issuer/credentials/analytics - Get credential analytics
POST /api/v1/issuer/credentials/export - Export credentials to CSV

Batch Processing¶

POST /api/v1/issuer/batch/process - Start batch credential processing
GET /api/v1/issuer/batch/{batchId}/status - Get batch processing status
GET /api/v1/issuer/batch/{batchId}/results - Get batch processing results

Dependencies & Prerequisites¶

Backend Dependencies¶

VNF Integration:
@velocitycareerlabs/data-loader - Official VNF batch issuing tool
VNF Credential Agent (provided by VCL, co-located infrastructure)
Core Processing:
csv-parser - CSV file processing
multer - File upload handling
handlebars - VNF template processing
qrcode - QR code generation
Communication:
nodemailer - Configurable email notifications
SMS gateway integration (optional)

Frontend Dependencies¶

UI Components:
react-dropzone - File upload interface
react-table - Data table components
react-hook-form - Form management with validation
Utilities:
date-fns - Date formatting
recharts - Analytics charts for credential dashboard

Infrastructure Requirements¶

VNF Credential Agent: Co-located with platform (managed by VCL)
Email Service: Configurable SMTP for credential delivery
File Storage: QR code and template storage
Database: Employee and credential tracking

REC MVP Workflow Integration¶

Complete Employee-to-Credential Flow (REC Compliant)¶

Organization Onboarding: KYB verification via Velocity Network Registrar API
Employee Creation: Create employee records via web form or CSV upload
Employee Management: Maintain employee database with unique Employee IDs
Manual Credential Creation: Issue individual EmploymentPastV1.1 credentials via web form
Batch Credential Processing: CSV-based bulk issuance using VNF data-loader
Credential Delivery: Email with configurable landing pages and QR codes
Credential Management: Track status (Pending, Issued, Claimed, Expired)
Analytics & Reporting: CSV exports and compliance reports

VNF Batch Issuing Integration (Official Process)¶

CSV Preparation: Employee email (first column) + Employee ID + credential data
Template Processing: Handlebars template with VNF variables
Data-Loader Execution: npx @velocitycareerlabs/data-loader batchissuing
Output Generation: QR codes (qrcode-[EMAIL].png) and deep links
Status Tracking: Monitor credential claims and verification
Email Distribution: Configurable templates per organization (REC requirement)

VNF Sample Templates¶

EmploymentPastV1.1 Template (Handlebars)¶

{
  "type": ["EmploymentPastV1.1"],
  "issuer": {
    "id": "{{{did}}}",
    "name": "{{{organizationName}}}",
    "type": "Organization"
  },
  "credentialSubject": {
    "vendorUserId": "{{{email}}}",
    "type": "EmploymentSubject",
    "employeeId": "{{{employeeId}}}",
    "person": {
      "type": "Person",
      "givenName": "{{{firstName}}}",
      "familyName": "{{{lastName}}}",
      "email": "{{{email}}}",
      "telephone": "{{{phone}}}"
    },
    "employment": {
      "type": "Employment",
      "jobTitle": "{{{jobTitle}}}",
      "department": "{{{department}}}",
      "startDate": "{{{startDate}}}",
      "endDate": "{{{endDate}}}",
      "employmentStatus": "{{{employmentStatus}}}",
      "workLocation": "{{{workLocation}}}",
      "organization": {
        "type": "Organization",
        "name": "{{{organizationName}}}",
        "identifier": "{{{organizationId}}}"
      },
      "supervisor": {
        "type": "Person",
        "name": "{{{supervisorName}}}",
        "email": "{{{supervisorEmail}}}",
        "jobTitle": "{{{supervisorTitle}}}"
      },
      "compensation": {
        "type": "MonetaryAmount",
        "value": "{{{salaryAmount}}}",
        "currency": "{{{currency}}}",
        "period": "{{{salaryPeriod}}}"
      },
      "performance": {
        "rating": "{{{performanceRating}}}",
        "skills": "{{{skills}}}",
        "responsibilities": "{{{responsibilities}}}"
      },
      "termination": {
        "reason": "{{{reasonForLeaving}}}",
        "eligibleForRehire": "{{{eligibleForRehire}}}"
      }
    }
  }
}

Sample CSV Format¶

email,employeeId,firstName,lastName,phone,jobTitle,department,startDate,endDate,employmentStatus,workLocation,supervisorName,supervisorEmail,supervisorTitle,salaryAmount,currency,salaryPeriod,performanceRating,skills,responsibilities,reasonForLeaving,eligibleForRehire
john.smith@company.com,EMP001,John,Smith,+44123456789,Software Developer,Engineering,2022-01-15,2024-03-30,terminated,London UK,Jane Doe,jane.doe@company.com,Engineering Manager,75000,GBP,annual,excellent,"JavaScript, React, Node.js","Developed web applications and APIs",career-change,yes

Acceptance Criteria¶

Phase 1: Employee Management ✅¶

Complete employee CRUD operations with unique Employee ID generation
CSV upload for bulk employee creation (500+ records supported)
Employee search, filtering, and pagination
Data validation aligned with VNF EmploymentPastV1.1 schema
Multi-tenant data segregation per organization

Phase 2: Manual Credential Creation ✅¶

Web form for individual EmploymentPastV1.1 credential creation
Employee lookup by Employee ID with auto-fill functionality
Integration with VNF Credential Agent for credential generation
Support for EmailV1.0, PhoneV1.0, DriversLicenseV1.0 identity verification
Configurable email templates and landing pages per organization

Phase 3: VNF Batch Credential Issuance ✅¶

Integration with @velocitycareerlabs/data-loader for batch processing
CSV-based bulk credential issuance (500+ employees)
Handlebars template processing with VNF variables
QR code generation (qrcode-[EMAIL].png) and deep link creation
Batch processing status tracking and error handling

Phase 4: Credential Management Dashboard ✅¶

Credential analytics dashboard (Total Issued, Claimed, Pending, Expired)
Credential list with search, filtering, and pagination
Bulk credential operations and status updates
CSV export functionality for compliance reporting
Credential verification status tracking

Phase 5: REC Compliance & Integration ✅¶

Organization onboarding via Velocity Network Registrar API
KYB verification integration
Configurable branding (colors, images, videos) per organization
Multi-factor authentication with passkey support
GDPR compliance with data retention and deletion policies
Audit logging for all credential operations
99.9% uptime SLA with disaster recovery

Estimated Timeline¶

Week 1-4: 20 days - Week 1 (Days 1-5): Employee management system (backend + frontend) - Week 2 (Days 6-10): Manual credential creation and CSV employee upload - Week 3 (Days 11-15): VNF batch issuing integration and batch credential processing - Week 4 (Days 16-20): Credential management dashboard and testing

Blockers & Risks¶

Dependency: VNF SDK integration and credential agent setup
Risk: Large batch processing performance with 500+ employees
Blocker: Email/SMS service configuration for credential distribution
Risk: CSV format variations and data validation complexity
Dependency: QR code storage and serving infrastructure