Phase 2: Batch Issuance Pipeline - POC Task¶

🎯 VNF SDK Reference Implementation¶

PRIMARY REFERENCE: `vnf-wallet-sdk-nodejs-main/`¶

All Phase 2 batch issuance tasks MUST follow the official VNF SDK sample application patterns

Key Reference Files: - Credential Manifest: packages/sample-server/src/routes/Issuing.ts:15 - getCredentialManifest workflow - Generate Offers: packages/sample-server/src/routes/Issuing.ts:25 - generateOffers implementation - Check Offers: packages/sample-server/src/routes/Issuing.ts:34 - checkForOffers workflow - Finalize Offers: packages/sample-server/src/routes/Issuing.ts:44 - finalizeOffers completion - Frontend Flow: packages/sample-app/src/screens/MeinScreen.tsx:140 - Complete issuance workflow

Overview¶

CORE CREDENTIALING PHASE: Implement the complete batch credential issuance pipeline following Velocity Network Foundation architecture and the 3-phase workflow using official VNF SDK patterns.

Velocity Architecture Alignment¶

This phase implements the core credentialing engine described in the Velocity Phase Explanations with VNF SDK integration: - Company Admin uploads employee CSV - System validates and processes employee data using VNF SDK patterns - Creates credential offers via VNF SDK generateOffers() - Generates VNF-compliant claim links and sends emails - Tracks issuance status using VCLExchange and VCLOffers entities

Prerequisites¶

Phase 1 MUST be completed: Organization status = ISSUER_ENABLED
Company Admin role must be properly configured
Organization-scoped access must be enforced

Backend Tasks¶

1. Organization Status Guard¶

Task: Enforce organization status validation
Create issuer-status.guard.ts
Block all credential operations unless organization status = ISSUER_ENABLED
Return appropriate error messages for each status:
- DRAFT: "Organization setup not completed"
- KYB_PENDING: "KYB verification in progress"
- KYB_APPROVED: "Issuer capabilities not yet enabled"
- SUSPENDED: "Credential issuance suspended"
Apply guard to all credential-related endpoints

2. Enhanced CSV Upload with Organization Context¶

Task: Update CSV upload to include organization validation
Update upload.controller.ts
Add organization status validation before upload
Include organization context in all employee records
Add organization-specific validation rules
Implement organization data isolation

3. Batch Issuance Service (Velocity-Aligned)¶

Task: Implement proper batch issuance workflow
Create velocity-batch-issuance.service.ts

Follow Velocity workflow:

1. validateEmployeeData(employees, organizationId)
2. createIssuanceBatch(employees, organizationId)
3. generateCredentialOffers(batch) // via Velocity CA
4. generateClaimTokens(offers)
5. queueEmailNotifications(offers)
6. updateBatchStatus(batchId, 'PROCESSING')

Add proper error handling and rollback mechanisms
Implement organization-scoped batch processing

4. Velocity Credential Agent Integration¶

Task: Proper VCA integration following Velocity standards
Update vnf-credential.service.ts
Implement organization DID validation
Add credential schema validation

Follow Velocity credential offer creation:

const credentialOffer = await velocityCA.createCredentialOffer({
  organizationDid: organization.did,
  credentialType: 'PastEmploymentCredential',
  credentialData: employmentData,
  expirationDays: 30
});

Add proper rate limiting and retry logic

5. Issuance Status Management¶

Task: Comprehensive status tracking aligned with Velocity states

Update credential offer status enum:

enum IssuanceStatus {
  PENDING = 'pending',           // Employee queued
  OFFER_CREATED = 'offer_created', // Offer generated by CA
  EMAIL_SENT = 'email_sent',     // Email sent
  CLAIMED = 'claimed',           // Employee claimed
  FAILED = 'failed'              // Issuance failed
}

Implement status transition validation
Add audit trail for all status changes

6. Email Integration with Claim Links¶

Task: Generate secure claim links and send emails
Update notification.service.ts

Generate secure claim tokens:

const claimToken = jwt.sign({
  credentialOfferId: offer.id,
  employeeEmail: employee.email,
  organizationId: organization.id,
  expiresAt: Date.now() + (30 * 24 * 60 * 60 * 1000) // 30 days
}, process.env.CLAIM_TOKEN_SECRET);

Create claim URLs: ${baseUrl}/claim/${claimToken}
Send personalized emails with claim instructions

Frontend Tasks¶

1. Organization Status Validation¶

Task: Prevent access to credential features for non-enabled orgs
Create OrganizationStatusCheck.tsx
Check organization status before showing credential features
Display appropriate setup messages for each status
Redirect to organization setup if needed

2. Enhanced Upload Interface¶

Task: Update upload interface with organization context
Update EmployeeUpload.tsx
Add organization status indicator
Show organization-specific upload guidelines
Display organization branding and context
Add organization data validation

3. Batch Processing Dashboard¶

Task: Real-time batch processing monitoring
Create BatchProcessingDashboard.tsx
Show batch processing stages:
- Upload → Validation → Credential Generation → Email Sending → Tracking
Display real-time progress with WebSocket updates
Add batch pause/resume controls
Show detailed error reporting

4. Credential Offer Management¶

Task: Manage credential offers and their lifecycle
Create CredentialOfferManager.tsx
Display credential offers with status indicators
Add bulk operations (resend emails, regenerate offers)
Show claim link generation and sharing
Implement offer expiration management

5. Issuance Analytics¶

Task: Track issuance performance and success rates
Create IssuanceAnalytics.tsx
Show issuance success rates by organization
Display processing time metrics
Add failure analysis and error categorization
Generate issuance performance reports

Workflow Implementation¶

Complete Batch Issuance Flow¶

flowchart TD
    A[Company Admin Login] --> B{Organization Status}
    B -->|ISSUER_ENABLED| C[Upload Employee CSV]
    B -->|Other Status| D[Show Setup Required]
    C --> E[Validate CSV Data]
    E --> F{Validation Passed?}
    F -->|No| G[Show Validation Errors]
    F -->|Yes| H[Create Issuance Batch]
    H --> I[Generate Credential Offers via VCA]
    I --> J[Create Claim Tokens]
    J --> K[Generate Claim URLs]
    K --> L[Send Email Notifications]
    L --> M[Update Dashboard Status]
    M --> N[Track Claim Events]

Organization Status Enforcement¶

flowchart TD
    A[API Request] --> B[Check Organization Status]
    B --> C{Status = ISSUER_ENABLED?}
    C -->|Yes| D[Process Request]
    C -->|No| E[Return Status Error]
    E --> F[Show Setup Instructions]
    D --> G[Continue with Credential Operations]

API Endpoints (Updated)¶

Batch Issuance Endpoints¶

// All endpoints require organization status = ISSUER_ENABLED
POST /api/v1/issuer/batches/create
GET /api/v1/issuer/batches/{batchId}/status
PUT /api/v1/issuer/batches/{batchId}/pause
PUT /api/v1/issuer/batches/{batchId}/resume
GET /api/v1/issuer/batches/history

Credential Offer Endpoints¶

GET /api/v1/issuer/credential-offers
POST /api/v1/issuer/credential-offers/{id}/regenerate
POST /api/v1/issuer/credential-offers/{id}/resend-email
GET /api/v1/issuer/credential-offers/{id}/claim-link

Organization-Scoped Analytics¶

GET /api/v1/issuer/analytics/issuance-rates
GET /api/v1/issuer/analytics/success-rates
GET /api/v1/issuer/analytics/processing-times
GET /api/v1/issuer/analytics/failure-analysis

Database Schema Updates¶

Organization Context in Batches¶

ALTER TABLE upload_sessions 
ADD COLUMN organization_id UUID REFERENCES organizations(id),
ADD COLUMN organization_status VARCHAR(20),
ADD CONSTRAINT check_issuer_enabled 
    CHECK (organization_status = 'issuer_enabled');

Enhanced Credential Offers¶

ALTER TABLE credential_offers
ADD COLUMN organization_id UUID REFERENCES organizations(id),
ADD COLUMN claim_token VARCHAR(500),
ADD COLUMN claim_url VARCHAR(500),
ADD COLUMN expires_at TIMESTAMP DEFAULT (NOW() + INTERVAL '30 days');

CREATE INDEX idx_credential_offers_org ON credential_offers(organization_id);
CREATE INDEX idx_credential_offers_token ON credential_offers(claim_token);

Velocity Integration Details¶

Credential Agent Configuration¶

const velocityConfig = {
  environment: process.env.VNF_ENVIRONMENT || 'sandbox',
  apiKey: process.env.VNF_API_KEY,
  organizationDid: organization.did, // From Phase 1
  credentialSchemas: {
    employment: 'employment-verification-v1.0'
  },
  rateLimits: {
    maxRequestsPerMinute: 60,
    maxBatchSize: 100
  }
};

Employment Credential Schema¶

const employmentCredential = {
  credentialType: 'PastEmploymentCredential',
  issuer: organization.did,
  credentialSubject: {
    employeeName: `${employee.firstName} ${employee.lastName}`,
    employeeId: employee.id,
    jobTitle: employee.jobTitle,
    department: employee.department,
    employmentStartDate: employee.startDate,
    employmentEndDate: employee.endDate,
    employerName: organization.name,
    employerDID: organization.did
  },
  issuanceDate: new Date().toISOString(),
  expirationDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
};

Dependencies & Prerequisites¶

Critical Phase 1 Dependencies¶

Organization status = ISSUER_ENABLED (mandatory)
Organization DID properly configured
Company Admin role with organization scope
KYB approval completed

Technical Dependencies¶

Velocity Credential Agent access
Email service configuration
JWT token management
WebSocket infrastructure for real-time updates

Acceptance Criteria¶

Organization Status Enforcement¶

All credential operations blocked unless organization = ISSUER_ENABLED
Appropriate error messages for each organization status
Organization context included in all operations
Data isolation enforced between organizations

Batch Issuance Pipeline¶

CSV upload validates organization status first
Batch processing follows Velocity workflow exactly
Credential offers created via Velocity Credential Agent
Secure claim tokens generated with proper expiration
Email notifications sent with claim links
Real-time status updates throughout pipeline

Performance & Reliability¶

Process 500+ employee records within 5 minutes
Handle VCA rate limits with proper retry logic
Maintain data consistency during failures
Support concurrent batch processing
Generate comprehensive audit trails

Estimated Timeline¶

Week 3-6: 20 days (CORE IMPLEMENTATION) - Week 3: Organization status enforcement and CSV updates - Week 4: Velocity Credential Agent integration - Week 5: Batch processing pipeline and email system - Week 6: Frontend interfaces and real-time tracking

Blockers & Risks¶

CRITICAL: Phase 1 must be completed first
Blocker: Velocity Credential Agent access and configuration
Risk: VCA rate limiting affecting batch processing
Dependency: Organization DID registration and validation
Risk: Email deliverability and claim link security

⚠️ IMPORTANT: This phase can ONLY be implemented after Phase 1 (Organization Foundation) is completed and organizations have ISSUER_ENABLED status.

Phase 2: Batch Issuance Pipeline - POC Task¶

🎯 VNF SDK Reference Implementation¶

PRIMARY REFERENCE: vnf-wallet-sdk-nodejs-main/¶

Overview¶

Velocity Architecture Alignment¶

Prerequisites¶

Backend Tasks¶

1. Organization Status Guard¶

2. Enhanced CSV Upload with Organization Context¶

3. Batch Issuance Service (Velocity-Aligned)¶

4. Velocity Credential Agent Integration¶

5. Issuance Status Management¶

6. Email Integration with Claim Links¶

Frontend Tasks¶

1. Organization Status Validation¶

2. Enhanced Upload Interface¶

3. Batch Processing Dashboard¶

4. Credential Offer Management¶

5. Issuance Analytics¶

Workflow Implementation¶

Complete Batch Issuance Flow¶

Organization Status Enforcement¶

API Endpoints (Updated)¶

Batch Issuance Endpoints¶

Credential Offer Endpoints¶

Organization-Scoped Analytics¶

Database Schema Updates¶

Organization Context in Batches¶

Enhanced Credential Offers¶

Velocity Integration Details¶

Credential Agent Configuration¶

Employment Credential Schema¶

Dependencies & Prerequisites¶

Critical Phase 1 Dependencies¶

Technical Dependencies¶

Acceptance Criteria¶

Organization Status Enforcement¶

Batch Issuance Pipeline¶

Performance & Reliability¶

Estimated Timeline¶

Blockers & Risks¶

PRIMARY REFERENCE: `vnf-wallet-sdk-nodejs-main/`¶