Skip to content

Milestone: M3 — Issuing Functionality | SOW Reference: FR1 (also feeds M3-04, M3-05, M3-12) | Requirement Clarity: ✅ Clear | Dev Status: 🟢 Prototyped in POC — confirmed implemented per commit "Implement employee CSV bulk upload/export" Moved from docs/requirements/tasks/POC/02-employee-upload-module.md — unmodified below.

M3-03 VNF Batch Credential Issuance Module - REC MVP

🎯 Official VNF & REC Requirements

PRIMARY REFERENCES:

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

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: Official VNF Batch Issuing workflow for UK Employment sector using @velocitycareerlabs/data-loader to issue EmploymentPastV1.1 credentials via CSV upload with configurable email delivery and QR code generation.

Supported Credential Types (Official VNF Certified)

  • Primary: EmploymentPastV1.1 (Recommended) - Past employment credentials
  • Identity Verification: EmailV1.0 (default), PhoneV1.0, DriversLicenseV1.0

VNF Batch Issuing Process

  1. CSV Upload: Employee data with email as first column + Employee IDs
  2. Template Processing: Handlebars template with VNF variables
  3. Data-Loader Execution: npx @velocitycareerlabs/data-loader batchissuing
  4. Output Generation: QR codes (qrcode-[EMAIL].png) and deep links
  5. Email Distribution: Configurable templates per organization (REC requirement)

Backend Tasks

VNF Data-Loader Integration

  • Task: Implement official VNF batch issuing 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 (from Velocity Network Registrar)
    • -e [URL] - VNF Credential Agent server URL (co-located)
    • -a [AUTH_TOKEN] - Bearer token for Credential Agent authentication
    • -c [CSV_PATH] - CSV file path with employee data (email as first column)
    • -o [OFFER_TEMPLATE_PATH] - Handlebars template for EmploymentPastV1.1
    • -t [URL] - Terms and conditions URL (configurable per organization)
  • Optional Parameters:
    • -y [CREDENTIAL_TYPE] - Identity credential type (EmailV1.0, PhoneV1.0, DriversLicenseV1.0)
    • -x - Generate output CSV with deep links and QR code paths
    • --new - Create new disclosure for batch
    • --purpose [STRING] - Custom purpose text (max 64 chars)

CSV Upload Controller

  • Task: Create VNF-compliant CSV upload endpoint
  • Create batch-upload.controller.ts
  • Implement POST /api/v1/issuer/credentials/batch-upload endpoint
  • CSV Format Validation: Email (first column), Employee ID, firstName, lastName, etc.
  • Add Multer configuration for CSV file handling (max 10MB, .csv only)
  • Validate CSV structure matches VNF data-loader requirements

VNF Template Management

  • Task: Implement Handlebars template processing for VNF credentials
  • Create vnf-template.service.ts
  • Template Type: EmploymentPastV1.1 credential template
  • Variable Processing: {{{email}}}, {{{employeeId}}}, {{{firstName}}}, {{{lastName}}}, etc.
  • Store organization-specific template customizations
  • Validate template variables against CSV headers

Credential Issuance Tracking

  • Task: Track VNF batch processing and credential status
  • Create batch-issuance.entity.ts
  • Status Tracking: UPLOADING, PROCESSING, ISSUED, CLAIMED, EXPIRED, FAILED
  • Store QR code file paths (qrcode-[EMAIL].png)
  • Store deep links and disclosure information
  • Link to Employee IDs and organization

Email Distribution Service

  • Task: Implement configurable email delivery (REC requirement)
  • Create credential-email.service.ts
  • Configurable Templates: Per-organization email branding and content
  • Email Content: QR codes, deep links, configurable landing page URLs
  • Integration with organization branding settings (colors, images, videos)
  • Support for follow-up email campaigns

Frontend Tasks

VNF Batch Upload Interface

  • Task: Create VNF-compliant CSV upload component for credential issuance
  • Create BatchCredentialUpload.tsx
  • CSV Template Download: Provide VNF-compliant CSV template with required headers
  • File Validation: Email (first column), Employee ID, VNF credential fields
  • Implement drag-and-drop functionality using react-dropzone
  • VNF Format Validation: Ensure CSV matches data-loader requirements

Credential Template Configuration

  • Task: Interface for managing VNF Handlebars templates
  • Create TemplateManager.tsx
  • Template Editor: Handlebars template for EmploymentPastV1.1 credentials
  • Variable Mapping: Map CSV columns to template variables
  • Organization Branding: Configure email templates and landing pages
  • Preview Functionality: Preview credential output before batch processing

Batch Processing Dashboard

  • Task: Real-time VNF batch processing status and results
  • Create BatchProcessingDashboard.tsx
  • Processing Stages: Upload → Template Processing → VNF Data-Loader → QR Generation → Email Distribution
  • Real-time Status: Monitor data-loader execution and credential generation
  • Results Display: Show generated QR codes, deep links, and claim status
  • Error Handling: Display data-loader errors and failed credential generations

Credential Distribution Management

  • Task: Manage email distribution and credential delivery
  • Create CredentialDistribution.tsx
  • Email Campaign Management: Send credential emails with QR codes
  • Landing Page Configuration: Customize per-organization credential claim pages
  • Delivery Tracking: Monitor email delivery and credential claim rates
  • Follow-up Campaigns: Send reminder emails for unclaimed credentials

API Endpoints

VNF Batch Credential Endpoints

POST /api/v1/issuer/credentials/batch-upload - Upload CSV for VNF batch processing
POST /api/v1/issuer/credentials/batch-process - Execute VNF data-loader
GET /api/v1/issuer/credentials/batch/{batchId}/status - Get batch processing status
GET /api/v1/issuer/credentials/batch/{batchId}/results - Get QR codes and deep links
GET /api/v1/issuer/credentials/batch/history - List all batch processing history

Template Management Endpoints

GET /api/v1/issuer/templates - List available VNF credential templates
POST /api/v1/issuer/templates - Create new Handlebars template
PUT /api/v1/issuer/templates/{templateId} - Update template
GET /api/v1/issuer/templates/{templateId}/preview - Preview template with sample data

Email Distribution Endpoints

POST /api/v1/issuer/credentials/distribute - Send credential emails with QR codes
GET /api/v1/issuer/credentials/distribution/{batchId}/status - Email delivery status
POST /api/v1/issuer/credentials/follow-up - Send follow-up emails for unclaimed credentials

VNF Sample Templates & CSV Format

EmploymentPastV1.1 Handlebars Template

{
  "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}}}"
    },
    "employment": {
      "type": "Employment",
      "jobTitle": "{{{jobTitle}}}",
      "department": "{{{department}}}",
      "startDate": "{{{startDate}}}",
      "endDate": "{{{endDate}}}",
      "organization": {
        "type": "Organization",
        "name": "{{{organizationName}}}"
      }
    }
  }
}

Required CSV Format (VNF Data-Loader Compatible)

email,employeeId,firstName,lastName,jobTitle,department,startDate,endDate,organizationName
john.smith@company.com,EMP001,John,Smith,Software Developer,Engineering,2022-01-15,2024-03-30,Acme Staffing Solutions
jane.doe@company.com,EMP002,Jane,Doe,Project Manager,Operations,2021-06-01,2024-02-15,Acme Staffing Solutions

Dependencies & Prerequisites

VNF Integration Requirements

  • VNF Credential Agent: Co-located infrastructure (provided by VCL)
  • @velocitycareerlabs/data-loader: Official VNF batch issuing package
  • Organization DID: From Velocity Network Registrar API
  • Bearer Token: For Credential Agent authentication

Backend Dependencies

  • @velocitycareerlabs/data-loader - Official VNF batch issuing
  • handlebars - Template processing for VNF credentials
  • csv-parser - CSV file processing and validation
  • multer - File upload handling
  • qrcode - QR code generation (handled by data-loader)
  • nodemailer - Configurable email distribution

Frontend Dependencies

  • react-dropzone - CSV file upload interface
  • react-hook-form - Template configuration forms
  • monaco-editor - Handlebars template editor
  • recharts - Batch processing analytics

REC MVP Acceptance Criteria

VNF Batch Processing ✅

  • Integration with official @velocitycareerlabs/data-loader
  • Support for EmploymentPastV1.1 credential type
  • CSV upload with email as first column (VNF requirement)
  • Handlebars template processing with VNF variables
  • QR code generation (qrcode-[EMAIL].png) and deep links

Organization Compliance ✅

  • Configurable email templates per organization (REC requirement)
  • Customizable landing pages with branding (colors, images, videos)
  • Terms and conditions URL configuration
  • Multi-tenant data segregation

Credential Management ✅

  • Batch processing status tracking (Uploading, Processing, Issued, Claimed)
  • Email distribution with follow-up campaigns
  • Credential claim monitoring and analytics
  • CSV export of batch results with deep links (-x flag)

Performance & Scale ✅

  • Process 500+ employee records per batch
  • Support for multiple concurrent batch operations
  • Error handling for individual credential failures
  • Audit logging for compliance requirements

Estimated Timeline

Week 2-3: 10 days (After Employee Management System) - Day 1-3: VNF data-loader integration and template management - Day 4-5: CSV upload interface and validation - Day 6-7: Batch processing dashboard and status tracking - Day 8-9: Email distribution and credential delivery - Day 10: Testing and REC compliance validation

Blockers & Risks

  • Dependency: VNF Credential Agent setup and co-location
  • Risk: VNF data-loader performance with large batches (500+ records)
  • Blocker: Organization DID registration via Velocity Network Registrar
  • Risk: Email delivery rates and spam filtering
  • Dependency: Configurable branding system for multi-tenant organizations